Changelog¶
Each release is written in two blocks. What changed is the reference half: one line per change, naming the symbol, the row or the value that moved, and nothing else. Why it changed is the explanation half: the measurement, the defect it exposed, and what it cost. A release whose entry is already a short list of self-explaining lines carries the first block only.
The split is deliberate. A reader who wants to know whether an upgrade will break them should not have to read an essay to find out, and the essays are worth keeping: most of them record a measurement that is the only evidence behind a threshold this project enforces.
Unreleased¶
What changed¶
Added¶
check_figure.TYPE_CEILING_PT(defaultmath.inf),VENUE_TYPE_CEILING_PT(nature,nature-column: 7.0),VENUE_PANEL_LABEL_PT(nature,nature-column: 8.0) andtype_ceiling_pt(venue=None, *, panel_label=False), the stricter ofTYPE_CEILING_PTand the venue's row.load_config:venueselects the venuetype_ceiling_pt()reads; a later file settingvenueorCONTENT_WIDTH_PTreplaces it.check_palette.BRETTEL_TRITAN, the constants the tritan simulation reads.tests/test_cvd_oracle.py, checking them against DaltonLens-Python 0.1.5.daltonlens==0.1.5joins thedevgroup.test_a_tritan_gate_at_cvd_target_would_fail_okabe_itointests/test_palette.py.EXTERNAL_CLAIMS["cividis optimisation"], and threeRETRACTED_CLAIMSentries, intests/test_prose_claims.py.EXTERNAL_CLAIMS["vislint_mpl linting built figures"]andRETRACTED_CLAIMS["no other tool reading the built figure"].EXTERNAL_CLAIMS["alt text semantic levels"], andLundgardinGUIDE_CITED.check_figure.XHEIGHT_FLOOR_PT = 4.0andx_height_fraction(path).check_type_sizewarns when a string with a lowercase letter has an x-height underXHEIGHT_FLOOR_PTon the page, measured in the font that draws its lowercase glyphs. The[FIX]names the size that clears it, or a face with a taller x-height where the ceiling allows no larger.usetextext is not measured.style-guide.mdReferences: Legge & Bigelow (2011).EXTERNAL_CLAIMS["fluent print size"],RETRACTED_CLAIMS["7.5pt as the size where text is comfortable"], andLeggeinGUIDE_CITED.check_figure.SERIES_CONTACT_PX = 2.0, inNOT_CONFIGURABLE.check_figure.SHARE_SPAN_RATIO_MAX = 2.0.- Invariance tests in
tests/test_figure.py: draw order, stroke contact, second channel, vertex density, and label redundancy across scales. SHARE_SPAN_CASES,test_the_share_span_ratio_separates_the_adversarial_setandtest_same_process_small_multiples_mostly_share_at_the_ratiointests/test_figure.py.RETRACTED_CLAIMS["autoscaled small multiples landing well inside a span ratio of 2"].examples/gallery.py:classifiers,abundance,dose_responseandinterrupted, with their PNGs and entries on the gallery page.- Four tests in
tests/test_figure.pypinning the pair each one puts in front ofcheck_series_color, and sevenCHECKEDentries intests/test_alt_text_numbers.pyfor their alt text. check_palette.pair_separation(color_a, color_b):cvd,cvd_kind,cvd_severity,tritanandnormalfor one pair.EXTERNAL_CLAIMS["anomalous trichromacy the commoner form"],test_the_anomalous_share_is_the_sum_the_table_gives, andSharpeinGUIDE_CITED.
Changed¶
check_type_size: the floor ismin(TYPE_FLOOR_PT, ceiling); text over the ceiling fails. A bold, upright, one-lowercase-letter string is held toVENUE_PANEL_LABEL_PTinstead. The over-ceiling[FIX]gives the authored size,floor / scale. Where no base under the ceiling lifts a script toMATH_SCRIPT_FLOOR_PT, the script[FIX]namesLogFormatter()andtext.usetexinstead of raising the base.TYPE_FLOOR_PTis 6.0, not 7.5.check_palette.simulate(rgb, "tritan")uses Brettel, Viénot & Mollon (1997).CVD["tritan"], the Viénot 1999 matrix, is removed.style-guide.mdReferences: the Machado entry says severity 1.0 is scaled to match Brettel 1997; the Nuñez entry names cividis.- The
MACHADOcomment incheck_palette.pyand the docstring oftest_the_severity_matrices_belong_on_linear_light: the same Machado correction, and the tritan caveat is credited to DaltonLens 0.1.5. - The separation-floor comment in
check_palette.py: 10.4 is the mean of Stone et al.'s three per-axis fits. choosing-a-form.mdReferences: DOIs for Anscombe (1973) and Schenker & Gentleman (2001).style-guide.mdReferences: the Potluri library ranking is scoped to the 39,540 notebooks with images.- README "Where this sits": names vislint_mpl (McNutt & Kindlmann 2018) as prior art and drops "None of them reads the built result".
style-guide.md"Describe the figure" cites Lundgard & Satyanarayan (2022), added to its References.document()intests/test_prose_claims.pyaccepts a path from the root.check_line_weightholds major and minor tick marks toFURNITURE_FLOOR_PT.test_line_weight_still_does_not_measure_tick_marksbecomestest_line_weight_measures_tick_marks.check_line_weightholds marker outlines toFURNITURE_FLOOR_PTwhen_marker_outline_ptfinds they carry the mark: unfilled or hollow markers, or an edge colour that is neither the face nor the background. The background is_ground: the most common colour_ground_imageholds on the rims (_marks_rim) of the marks Agg draws inside their clip box and clip path (_drawn_rows)._ground_imagedraws everything before that artist, and aLine2D's own line (_own_line), in its axes and in each earlier axes whose box meets it (a twin's host).check_line_weightdraws that ground forward on one buffer (_ForwardGround), and only for an outline that differs from its fill._ground_imagereturns Agg's uint8 RGB.check_line_weightreads tick widths throughmarker_stroke_pt, socolor="none"ticks measure 0, and skips spines, ticks and gridlines on an axes withaxisonfalse and ticks and gridlines on a hidden axis.check_type_sizecompares on-page sizes to the floor and ceiling before rounding, with_PT_TOL = 1e-6of slack, as do the mathtext script floor andcheck_line_weight's three floors. Failing sizes and widths print to 0.01pt, rounded away from the limit.- The x-height
[FIX]names the largest size any low string needs under each maximum, body text and panel labels apart. - The x-height
[FIX]divides the unrounded need by the scale, advises to 0.01pt where 0.1pt lands over the maximum, and prints the page size the advised size gives.check_line_weight's three[FIX]s round widths up to 0.01pt. - The ceiling
[FIX]rounds the authored size down to 0.1pt, the x-height[FIX]rounds it up. check_series_colorgates every pair in a panel with a legend, as in one with marks and no line (scatter, orplotwith a marker only). Otherwise it gates these, each read inside the box its artist is clipped to:- area hues that are neighbours in draw order;
- every pair of line series whose strokes come within
SERIES_CONTACT_PXof touching; - each stroke and its nearest of another hue;
- a line and each area whose shape it enters.
A hue drawn only as lines takes no part in draw order.
- check_series_color: a pair under CVD_TARGET passes when a mark type,
dash, marker or hatch also separates the two series in some kind of artist
both draw (_carried). NORMAL_FLOOR is not excused.
- _carried reads error bars (_errorbar_bars) as a kind of their own, not
as lines.
- check_banking banks by arc length at constant area (Talbot, Gerth &
Hanrahan 2011), through _banking_factor, not by median absolute slope,
and drops only a line whose rise on the page is under its stroke width.
BANKING_FLAT_PX is retired: load_config warns (FutureWarning) and
skips it, as every RETIRED_KEYS key. The row's
detail gives the aspect factor: "ax0 banking wants the panel 130x
taller", or "3 line panels, 1.2-3.5x from banked".
- choosing-a-form.md and docs/gates.md describe the arc-length criterion;
Talbot et al. join the References and EXTERNAL_CLAIMS["arc length
banking"].
- check_palette.check reads dichromacy under Machado's severity 1.0 as well
as Viénot's, reported as severity 1.0, Machado.
- The severity claim above MACHADO and in style-guide.md: 0.13% of
244650 slot pairs, up to 10.7 dE, with #1a80b8 and #fb00e4 as the
example. RETRACTED_CLAIMS holds the 1.27% and #8e4dc7 version.
- test_the_sweep_leaves_dichromacy_to_the_vienot_matrices becomes
test_the_sweep_reads_dichromacy_under_both_models.
- check_overplotting's docstring no longer lists hollow markers and
transparency as remedies.
- The CMAP_WRAP_DE_MAX comment and style-guide.md: 1.0 is about 2 CIELAB,
not one JND. RETRACTED_CLAIMS holds the JND version.
- ORDINAL_DL_MIN and CMAP_SPAN_MIN state their CIELAB L* equivalents,
about 7.1 and 2.4.
- style-guide.md "What is evidence for them": Stone et al.'s per-axis model
fails three Okabe-Ito pairs at NORMAL_FLOOR, not one. Pinned in
test_the_size_model_itself_fails_three_okabe_ito_pairs.
- style-guide.md: why the gate stays in CAM02-UCS, and the two shipped-cycle
pairs Stone et al.'s model fails at 2 ND(50) under simulation, pinned in
test_the_size_model_at_2x_fails_two_shipped_pairs_under_simulation.
Szafir (2017) joins the References, EXTERNAL_CLAIMS["size model tested
range"] and GUIDE_CITED.
- check_redundancy counts a repeated axis title among panels on one scale
type whose limits could share an axis within SHARE_SPAN_RATIO_MAX, not
among panels with identical limits.
- check_series_color: a hidden legend does not make a panel gate every pair;
plot and scatter markers are compared as drawn paths; axvline and
axhline strokes are read through their own transform, in label attribution
too; the CVD [FIX] names dash, marker, hatch or mark type.
- _StrokeGaps without scipy uses a grid capped by GRID_PAIR_CAP.
- check_figure.NOT_CONFIGURABLE gains SERIES_CONTACT_PX, and its
GRID_PAIR_CAP reason names the contact test. config_keys() loses
SERIES_CONTACT_PX and gains SHARE_SPAN_RATIO_MAX.
- tab10's orange and green are quoted at dE 1.6 under protanopia, the number
the row prints, in SKILL.md, design.md and check_series_color.
- The SHARE_SPAN_RATIO_MAX comment states the range the adversarial set
allows, [1.6, 4.0), and its same-process miss count.
- The gallery count is twenty-four in gallery.py, the README, design.md,
the gallery page and the tests that count it.
- style-guide.md: anomalous trichromacy is 5.71% of European men and
dichromacy 2.28%, from Sharpe et al. (1999) Table 1.6, added to its
References.
- simulate_anomalous's docstring says below 1.0 is anomalous trichromacy,
and no longer says it is where most deficiency sits.
- check_figure._separation takes the panel's _data_artists from
check_series_color and measures each pair with pair_separation, not by
calling check_palette.check and parsing its detail strings.
check_palette._cvd_detail takes fix; _separation passes False.
- check_series_color warns, naming what is missing, when the
check_palette.py beside it has no pair_separation, _cvd_detail or
_normal_detail.
- check_series_color compares dashes by Line2D's on-off sequence, not by
get_linestyle(), and ignores the dash offset.
- _data_artists skips a Line2D with no stroke and no marker.
- _gated_pairs reads an area as the outlines _area_px returns, each path
through the transforms matplotlib draws it with, and stroke gaps exactly
through _StrokeGaps.
- _data_artists skips error bar caps (_errorbar_caps).
- _largest_sharable counts the largest group whose union of limits is
within SHARE_SPAN_RATIO_MAX of its narrowest span, not a chain of pairs.
- _banking_segments takes segments within each finite run of a line, and
reads the line through its own transform.
- _banking_factor reuses the surviving probe and stops at a 1e-9 bracket on
log(a).
- check_palette._cvd_views caches each colour's simulated views;
_separation_numbers reads distances from them.
- test_check_palette_still_imports_nothing_outside_the_standard_library
allows functools.
- check_line_weight, check_contrast_stack and _data_artists read each
InsetIndicator's rectangle and connectors with ax.patches
(_drawn_patches).
- pyproject.toml raises matplotlib's indicate_inset unpacking warning as an
error.
- examples/gallery.py (broadening) and
test_an_inset_connector_is_not_a_data_hue read the connectors from
InsetIndicator.connectors where indicate_inset_zoom returns one, and
index the tuple otherwise.
- check_text_readability tests casing with is not None, and composites
the text's alpha over its backdrop, or over its casing laid on the backdrop
at the opacity Agg draws the casing with (_halo_alpha), before measuring
contrast.
- _worst_backdrop takes alpha; _contrast_field_255 takes one colour or
one per pixel.
- check_mark_ratio skips invisible collections and the " " marker, and
reads plot markers through marker_extent_pt(..., stroked=False).
- marker_extent_pt takes stroked (default True).
- check_form flags bars on a linear axis whose limits are both below zero.
- _contact_fraction drops marks at a non-finite position or radius, masked
offsets included, before either path.
- check_overplotting and _marks_px place points through the artist's own
transform, and read lines through get_xydata.
- check_ink measures each pixel against _ground_image, which draws
_ground_layers on a fresh RendererAgg: the figure's and each
subfigure's patch, every figure-level artist some axes is drawn after,
and each axes' patch where axison and get_frame_on() hold.
- check_fonts expands each font.family entry: a generic name to its
font.<generic> list, a face name to itself.
- check_contrast_stack groups filled collections other than scatters, and
patches that _fills, by colour, not every entry in ax.collections, and drops a
graded run's own entries rather than every entry at one of its values.
- _corners measures the upright box through _text_only_extent.
- check_dual_axis pairs _all_axes, not fig.axes.
- _is_bold resolves weight names through font_manager.weight_dict.
- _artist_kind returns "line" for a LineCollection; _polyline_px
reads one through _path_px, and _gated_pairs takes its widest stroke
(_stroke_pt). _dash reads a LineCollection's _us_linestyles, and
_second_channel compares its dash.
- _tick_texts, _polar_radial_ticks, _furniture, _legend_text_ids,
_furniture_text_ids, check_identity_channel and
check_label_attribution walk _all_axes. _legend_text_ids,
check_identity_channel and _layout_kept walk _all_figures.
- describe is annotated -> Figure, which it returns.
- audit, and check_ink and check_text_readability called without a
canvas, put back the canvas, fig.dpi and _original_dpi the figure
arrived with (_on_own_canvas, _at_measure_dpi), and the axes positions,
subfigure boxes, sup* label positions and subplotpars (_layout_kept).
_authored_dpi is removed. _on_own_canvas moves the figure to a
FigureCanvasAgg on entry, and _renderer draws on it.
- tests/test_audit_idempotence.py audits every gallery, demo and
external-style figure twice.
- _measuring enters _on_own_canvas, _layout_kept, _at_draw_rc and
_at_measure_dpi once per figure, for audit, check_ink and
check_text_readability. @_measured runs check_banking, check_form,
check_line_weight, check_mark_ratio, check_overplotting and
check_series_color inside it, and draws the figure first when one is
called on its own.
- check_mark_ratio scales a scatter's sqrt(s) by its marker path's long
side (_marker_path_extent).
- check_overplotting scales it by the short side
(_marker_path_extent(..., short=True)).
"|" has a short side of 0, so its width is its stroke.
- check_mark_ratio, check_overplotting, _draws_nothing, _second_channel
and _marker_outline_pt test for no marker with
_no_marker, which takes a vertex-array marker.
- _over(src, src_alpha, dst), Agg's blend over an opaque ground, used by
_worst_backdrop and cased check_text_readability.
- _marks_px and _series_px skip masked and non-finite marks;
_marks_display is _marks_px inside _on_page and the artist's clip path.
- check_figure.GATE_RAISED and suggest_fixes.GATE_RAISED; suggest skips
a row whose detail opens with it.
- check_palette.check matches ink case-insensitively and with or
without the #.
- simulate_anomalous rounds severity to the nearest tenth half up.
Why it changed¶
A code review of the invariance round found draw order still deciding pairs.
Lines that never met passed with blue plotted between orange and green and
failed with the calls reordered, and plot(x, y, "o") clouds escaped both the
all-pairs rule and the contact test. Draw order is kept for areas, where it is
what a stacked bar puts side by side. A line against an area is carried by
mark type in the CVD row, so NORMAL_FLOOR is what it answers to.
make sweep over the 25 corpus figures records no verdict change; one detail
moves, in gallery-interrupted, where #d55e00 and #cc79a7 were neighbours
in draw order and are now not compared.
Pairwise joins in _largest_sharable chained: 0-1, 0-2 and 0-4 counted as
three panels for one sharey, which squashes 0-1 to a quarter. A dropped NaN
run was banked as one invented segment across the gap. get_linestyle()
returns '--' for every dash tuple. A vendored check_palette.py older than
pair_separation raised AttributeError out of audit.
Read against matplotlib 3.8.4 and 3.11.1, the versions CI runs:
Collection.get_window_extent is a null box for vlines on both and for
fill_between on 3.8.4, so a line crossing one was never compared with it.
plot(..., ls="none") without a marker draws nothing, and read as marks it
made its panel gate every pair.
A review of the stack found pairs still read off geometry the page does not
draw. An area was its bounding box, which for a band along the diagonal is the
panel. On a log axis get_path_collection_extents applied only the affine part
of the transform, so a band from 10 to 1000 missed a line inside it. Strokes
were read past the axis limits, so lines crossing only off the panel were
compared. Error bar caps are marker-only lines, so a capped panel compared
every pair. Two series each drawn as a line and a plain band failed with their
lines dashed apart, because the bands matched. Nearest strokes were read on 256
samples per stroke, every pair of samples of every pair of strokes: 6.9s on 120
random walks, now 0.27s with scipy and 0.08s without. 19 adversarial
series-pair cases go from 8 wrong to none on matplotlib 3.8.4 and 3.11.1. Of
400 seeded random-walk panels, 30 change pairs, 29 of them panels whose x
limits cut the lines; all 30 now match distances over every vertex pair, and
none did before. The corpus records no row change.
A review of the stack found the remaining line cull too strict. Dropping only
a line with no rise at all banked float noise: a metric converged at 0.95 with
noise of sd 1e-4 on a 0-1 axis wanted its panel 107x taller, and at sd 1e-6
10200x, where the exact level read no line panel. A line is now dropped when
its rise on the page is under its own stroke width, the width at which it
draws as a level line, so no constant is added. Loading a v0.10.0 file that
set BANKING_FLAT_PX raised ValueError.
TYPE_FLOOR_PT = 7.5 had no source. It shipped in the initial release, and
"7.5 is where it is comfortable" was added two days later. 6.0 is the minimum
PNAS publishes, already quoted in EXTERNAL_CLAIMS["journal type
floors"].
An x-height gate was built and rejected. Legge & Bigelow (2011) put the start of fluent reading at an x-height of 0.2 degrees, 4.0pt at 40cm, but that consensus is for continuous reading, not glanced labels. Gated, it failed 15 of the 40 SkillsBench figures that passed 7.5pt, under the Linux fonts the bench ran with. In 8 of the 15 the smallest failing strings were numerals, which stand near cap height and which x-height does not describe. Its body floor also moved with the installed fonts: 8.5pt in STIX Two Text, 8.9pt in STIXGeneral. It ships as the warning, on lowercase only.
Re-running the 66 SkillsBench scripts that reach a report or audit call,
the 40 that passed 7.5pt now pass in 27 and warn in 13. Of the 26 that failed,
23 still fail, every one on a venue ceiling, and 3 with text between 6 and
7.5pt now pass or warn. make sweep over the 21 corpus figures records no
verdict change; their smallest string is 9.0pt.
TYPE_FLOOR_PT = 7.5 sat above Nature's 7pt maximum, so no size passed both
(#107). In a SkillsBench A/B, 5 runs per arm on three Nature-placed tasks, all
5 with-skill text-size failures were text at 7.5 to 8.0pt. Capping the floor at the
ceiling adds no number the guides do not publish.
Rounding first passed docs/design.md's own failing case. The x-height [FIX] read the string
with the smallest x-height, so with 'dose' at 6.5pt in DejaVu Sans and 'time'
at 8.5pt in STIXGeneral it named 7.4pt, which 'time' already exceeds.
Rounded to the nearest 0.1pt, each [FIX] could name a size that fails its
own check: under Nature at scale 0.745 the ceiling fix named 9.4pt, 7.003pt on
the page, and a STIXGeneral string set at the advised 11.9pt still warned.
The x-height need was rounded before the scale divided it: DejaVu Sans at
scale 0.93 needs 7.31pt, rounded to 7.4, advised 8.0pt, 7.44pt on the page,
over a 7.4pt maximum, so the [FIX] said none fits; 7.9pt does.
check_line_weight printed its advice with :.2f, 1.34 at scale 0.745, which
is 0.998pt on the page. Sizes were rounded to 0.1pt before the compare, so
5.95pt passed a 6pt floor.
One x-height size for every string could advise a panel label's need for
body text over Nature's 7pt body maximum. No face bundled with matplotlib
reaches that case; the test fakes the fractions.
Viénot 1999 models protanopia and deuteranopia only. DaltonLens's review of
open-source simulators calls Brettel 1997 "the most solid and basically only
valid choice" for tritanopia. The oracle agrees to 4.7e-8 in linear RGB.
daltonlens is pinned exactly because the oracle calls a private method.
The tritan figure in the CVD separation row moves: Okabe-Ito's first three
slots read 12.2, not 12.5. make sweep over the 21 corpus figures records no
verdict change.
Tritan stays reported and ungated. Gating it at CVD_TARGET was measured and
rejected: Okabe-Ito's six series slots, all pairs, read tritan 10.1 (#E69F00
against #CC79A7). Of matplotlib 3.11.1's 28 style cycles cut to their first
3, 4 and 6 colours, 20 of 83 pass red-green on all pairs; a tritan gate would
fail one of those 20, Solarize_Light2 at 5.0. It would fail the recommended palette to catch one
style.
Three citations were checked against the papers' full text and did not hold.
Machado, Oliveira & Fernandes (2009) fit their 0.96 scale factor to "Brettel
et al.'s" surface, reference [4], Brettel 1997; the paper does not cite Viénot
1999, which simulate uses for protan and deutan. The tritan caveat came from
DaltonLens's Simulator_Machado2009, not from the authors. Nuñez, Anderton &
Renslow (2018) never mention Okabe-Ito or categorical palettes; the paper
optimises one continuous map. The 2.84 and 2.44 dE measurements behind the
linear-light choice are unchanged.
The same check found three smaller gaps. The module comment called 10.4 the difference half of observers notice, without saying it averages one fit per axis; the style guide already did. Potluri et al. rank charting libraries over the 39,540 notebooks with images, not their 100,000-notebook corpus. The two DOIs resolve in Crossref to the volume, issue and pages already printed.
The README read as if figure-gate were the first linter of built matplotlib
figures; vislint_mpl was, in 2018. Two tracked files are named README.md, and
document()'s error message asked for a path it could not resolve.
The alt-text advice to give numbers and direction had no source. Lundgard &
Satyanarayan's blind readers ranked statistics and trends most useful. No gate
follows: check_alt_text checks presence and length, and a description's
semantic level is not mechanically checkable.
Tick marks were skipped as matplotlib's defaults. A SkillsBench run printed
1.2pt ticks from a 9in figure at 3.6in: 0.48pt, under Science's 0.5pt minimum,
and the gate passed it. Every tick on the 21 corpus figures and on 84 figures
under matplotlib's 28 style sheets clears 0.5pt, so make sweep records no
verdict change.
A code review of the ceiling and stroke changes found defects in both. Under
Nature's 7pt maximum a first-level mathtext script renders at 4.9pt, so
matplotlib's default log ticks fail the 5pt script floor and the base cannot
rise; fontmath.ltx sets 5pt scripts under a 7pt base, so usetex passes.
Nature's guide asks for "8-pt bold, upright (not italic) and lowercase a, b,
c" panel labels, which the 7pt ceiling failed. A venue= argument dropped a
TYPE_CEILING_PT set as a house maximum, and a second load_config kept the
first file's venue ceiling. Ticks drawn in "none", furniture on an axes
switched off, and black outlines on a "none" axes background were each
misread.
check_line_weight did not measure marker outlines. Another run drew filled
markers with a 1.0pt black edge in the same 9in figure: 0.4pt printed. Held to
LINE_FLOOR_PT, outlines would fail gallery-field's 0.8pt star edge, so they
are held to FURNITURE_FLOOR_PT. Five seaborn sheets draw 0.24 to 0.48pt edges in the face
colour; those carry nothing and are skipped. The corpus records no verdict
change, and none of the 84 style-sheet figures fails.
A review on 2026-10-19 found four rows whose verdict moved with something the
reader never sees, or that failed a figure for doing what the row's [FIX]
asks. Orange and green lines that cross passed when blue was plotted between
them and failed with the calls reordered. The same pair drawn solid-and-circle
against dashed-and-square, with a legend, failed and was told to add
"direct labels/gaps/texture". BANKING_FLAT_PX = 0.5 culled every segment of
the saw wave once each was split into ten, so the panel the row exists for
read "no line panel". And two panels titled "Accuracy" at 0 to 1 and 0 to
1000 were told to sharey.
A legend makes the reader identify each series against a swatch, the task the
floors' multiples were chosen for, so every pair is compared. Measured
over the first two to six colours of every registered qualitative colormap
and the theme, 15 of 70 pass adjacent and fail all-pairs; these now fail as
legended lines. Set1 (blue and purple, dE 4.6 under deuteranopia) and Paired
(green and red, 5.6) are among them. So is matplotlib's okabe_ito from five
colours, on orange #e69f00 against yellow #f0e442 at 20.8 against
NORMAL_FLOOR = 21.0.
The corpus records no verdict change. gallery-broadening reads three line
panels for banking instead of one: the other two had been culled whole.
demo with its legend now reports orange against green, dE 20.7.
The severity sweep compared Viénot at 1.0 with Machado below it. Over the
same 244650 slot pairs, 1.35% clear CVD_TARGET under Viénot and miss it at a
lower Machado severity; 0.13% clear it under both dichromacy models and miss
it below. Nine tenths of the published effect was the two models disagreeing.
The documented pair, #8e4dc7 against #1402ef, reads 7.97 under Machado's
own severity 1.0, below its 8.3 at 0.9. Of the 309 pairs only the sweep
fails, 177 clear NORMAL_FLOOR; no other row catches them, so the sweep stays.
Dropping Viénot for a single-model sweep would pass 0.59% of pairs Viénot calls too close. Reading both tightens instead: 0.44% of pairs newly fail. Against colorspacious, which sweeps Machado to 100, false passes on the oracle test's 4005 pairs go from 9 to 0. The corpus records no verdict change.
CMAP_WRAP_DE_MAX called one CAM02-UCS unit a just-noticeable difference, with
no source. Through the file's own bridge, a median 1.99 CIELAB per unit, it is
twice the theoretical 2-degree JND Stone et al. give. The threshold rests on
the registry instead: the two twilights wrap at 0.000 and 0.376, the nearest
diverging map at 27.963.
ORDINAL_DL_MIN and CMAP_SPAN_MIN gate on OKLab lightness differences, which
the same file says have no published unit. Along ten sequential maps one OKLab
L is a median 118 L, so 0.06 is about 7.1 L. Stone et al.'s lightness fit
puts ND(50) at 5.45 L* for a two-degree patch and 7.33 for a 0.333-degree
target, so adjacent ordinal steps sit just under the half-of-observers line on
a hairline. No threshold moved.
The style guide called Okabe-Ito missing NORMAL_FLOOR at exactly the pair the
shipped cycle drops "the strongest argument these numbers have". In Stone et
al.'s own model, at 4 ND(50) for a 0.333-degree target, sky blue against blue
(3.42) and orange against vermillion (3.59) miss too, and the shipped cycle
keeps both. The CAM02-UCS bridge is a median, and it is what passes them.
The metric stays. The 4 ND(50) that fails those pairs is past the 2 ND(50) Szafir (2017) measured to. Switching would fail the shipped cycle on four pairs, and no in-band six-colour cycle drawn from Okabe-Ito and Tol's sets passes it (0 of 38760). The two simulated pairs it fails at 2 ND(50), inside the measured range, are recorded rather than gated, because no study ties an ND(50) multiple to identifying a series.
A code review of this branch found the invariance fixes had broken their own
rows. The slope cull read a panel banked too flat throughout as "no line
panel": nine points at page slope 0.0096 warned before and passed after. Exact
limits as the redundancy key missed two "Accuracy" panels autoscaled to 0.10
to 0.95 and 0.12 to 0.97. A scatter circle beside a plot circle excused a
dE 1.6 pair as carried by a second channel. An axvline crossing a line was
read at data y 0 to 1 and never compared. A hidden legend switched the panel to
all-pairs. The scipy-free contact test peaked at 784 MiB on two 100000-vertex
rings; the grid peaks under 200 MiB and takes 1.07s where scipy takes 1.18s on
three 20000-point lines. The corpus records no verdict change.
SHARE_SPAN_RATIO_MAX = 2.0 was a judgement the corpus cannot test: none of
its 21 figures has two panels in a row or column naming one quantity. An
adversarial set takes its place. Its panels that should share an axis reach
1.60 and its panels that should not start at 4.00, so any factor in [1.6, 4.0)
separates them. Moving the constant to 1.5 or 4.0 fails one case each. Of 900
seeded same-process small multiples (normal, lognormal on a log axis, Poisson;
2 to 6 panels of 10 to 100 points), 3 join no pair at 2.0 and none at 2.5. The
constant stays at 2.0: the cases between 2 and 3 have no right answer to test,
and a miss leaves the row silent where a false fire fails the figure.
The corpus could not see the series-colour changes above. 12 of its 16 panels
that gate two or more hues compared one pair, orange against sky blue; none had
a figure legend, a coloured reference line or a pair a second channel had to
carry; #0072B2, #D55E00 and #CC79A7 were never drawn. The four new
figures each reach one path, modelled on CC-BY figures in PLOS ONE, cited in
each builder's comment. Swept with the checker from before
this round, they move two verdicts: gallery-dose-response fails Series color
without the second-channel excuse, and gallery-interrupted fails Label
attribution while axvline is read at data y 0 to 1. The two legend figures
move Series color detail from dE 15.1 and 39.5 to 12.8. Before the code-review
round, one verdict moves. The 21 existing figures record no verdict change.
_separation read dE and tritan back out of check's detail strings with a
regex, so rewording a detail string could have moved a verdict, and it
harvested each panel's artists a second time. The two separation rows' detail
strings are now written once, in check_palette, for both callers. Verdicts
and details did not move: the 25-figure sweep is byte-identical before and
after, and so is check_series_color on 400 seeded random figures, 165 of them
failing and 37 carried by a second channel.
simulate_anomalous said severities below 1.0 are "where most colour vision
deficiency actually sits", with no source. Birch (2012), already cited, gives
totals only. Sharpe, Stockman, Jägle & Nathans (1999) Table 1.6 splits 45 989
European men: 1.08% protanomaly, 4.63% deuteranomaly, 1.01% protanopia, 1.27%
deuteranopia, so anomalous trichromats are 5.71 of the 7.99 points. The
sourced claim lives in the style guide, where the ledger can hold it.
Banking read Cleveland's median absolute slope, which depends on how a curve
was sampled: y = sqrt(x) with 40 points spaced three ways needed its aspect
changed 1.9x, 0.949x or 2.51x. Talbot, Gerth & Hanrahan (2011) name this
defect in three of the four earlier criteria and recommend minimising arc
length at constant area, which reads 1.37x to 1.38x on all three. Arc length
also needs no cull for flat segments, so BANKING_FLAT_SLOPE, added earlier in
this release and a judgement, is gone with it. The 25-figure corpus records no
verdict change; ten Banking details change wording.
matplotlib 3.10 returns an InsetIndicator from indicate_inset_zoom and
warns that "From 3.12 it will no longer be possible to unpack the return value
into two elements." Both call sites unpacked it. Raised as an error, the
warning fails CI's latest-matplotlib jobs on a call site that unpacks; the
3.8.4 job takes the tuple branch. On 3.10 and later the rectangle and
connectors are drawn by the InsetIndicator, not from ax.patches, so
check_line_weight passed a 0.1pt frame, and
test_an_inset_connector_is_not_a_data_hue passed with the ConnectionPatch
exclusion it pins deleted. check_contrast_stack read the rectangle's alpha
of 0.5 as a level on 3.8.4 and not on 3.11.1.
A review of the gates against matplotlib's artist model found ten wrong
verdicts, each reproduced by a test in tests/test_figure.py. An ndarray
casing colour raised in if halo_color: and the crash read as a hard FAIL.
Black text at alpha 0.15 passed. "." at ms 12 beside "o" at ms 5 failed at
5.8x; they draw 6pt and 5pt. A hidden s=2000 scatter failed a figure at 200x.
Negative bars on ylim(-9, -3) passed. One NaN in a scatter made cKDTree
raise. A transform=ax.transAxes scatter was placed through transData, and
a marker cloud on a date axis was never measured because
asarray(get_xdata(), dtype=float) raised on datetimes. Under ggplot and
seaborn-v0_8-darkgrid one sine line read 0.95 ink, because the figure corner
is white and the axes face is grey; test_external_style_corpus asserted that
fire as a property of dark grounds. font.family = "NoSuchFontXYZ" left the
substitution check an empty list. Mark ratio leaves edge strokes uncounted on
both sides, as its scatter side already did: counted, gallery-field moves
from 4.8x to 5.1x and fails a threshold calibrated without them. The 25-figure
corpus records no verdict change; gallery-field's Mark ratio detail moves
from 4.8x to 4.4x, because a star's path is narrower than its markersize.
The same review found code that disagreed with its own comment or with
matplotlib; each case has a test that fails on the old code. Three scatters
in one colour collapsed to one alpha level, and a four-band axvspan fan
counted four. A rotated annotation with an arrow fell back to its axis-aligned
box, 5x the ink at 45 degrees. "demibold" and "demi" are weight 600 in
matplotlib and were read as regular. vlines read as an area.
sub.twinx() lands in fig.axes and the inset sub does not, so
check_dual_axis compared the twin with every frame but its own. Seven helpers
and gates still walked fig.axes, so an inset's ticks, legend, title and face
went unseen; a legend inside an inset left check_identity_channel warning.
describe returned fig under a -> None signature; it still returns fig, so callers that chain it keep working. savefig restores the
canvas it swaps (FigureCanvasBase._switch_canvas_and_return_print_method);
audit did not, so an audited figure no longer showed in its window.
suggest offered figure remedies for a gate that crashed. #52514E as ink
did not exempt #52514e. round is half-to-even, so severity 0.05, 0.25,
0.45, 0.65 and 0.85 read a tenth low. The corpus records no verdict change. Text collision
counts fewer objects on gallery-broadening, gallery-counts and
gallery-secondary-scale, because inset and secondary-axis tick labels now
take the tick exemption host ticks already had.
Reviewing those fixes found more. check_ink read 1.00 under ggplot with
axis("off"), on a grey SubFigure, and over a translucent figure face: Agg
skips the axes patch unless axison and frameon hold, and blends onto the
transparent white it clears to. scatter(marker=".", s=36) beside
plot(".", ms=6), the same dot, read 4.0x, and a "." cloud at s=36 warned
72% merging where the plot spelling passed. A vertex-array marker raised in
both mark gates. A PatchCollection fan was not grouped. On matplotlib 3.8.4
the canvas __init__ sets _original_dpi = fig.dpi, so a second audit left
savefig writing at 150 dpi. savefig writes at _original_dpi and puts
fig.dpi back as it found it, so a HiDPI figure now comes back on its doubled
dpi, matching the canvas it is handed back to. Two tests required the authored
dpi on the assumption that the doubled dpi doubled the output; on 3.8.4 and
3.11.1 it does not. The corpus records no verdict change.
Verifying those fixes found two more. A layout engine runs on every draw from
where the last draw left the axes, and audit left them moved. Under
seaborn-v0_8-talk the first audit passed a panel that the second warned
on, at 19.7x from banked and 0.86 ink; the next savefig then wrote it 0.08
of the figure wide. twinx hides the twin's patch, so the host's face is the
twin's ground; read against the figure's white, a ggplot twin measured 0.94
ink and warned. That fix took one ground per panel from a host containing it
whole. An axes half over a grey one then read the grey half as ink, 0.41 and
0.47 where the render holds 0.06 and 0.05, and a grey polar face read its
corners as ink. The ground is now composited per pixel. The corpus records no
verdict change.
Six public gates read display geometry and, called on their own, measured it
at the dpi the author set. With three lines 0.03 apart, check_series_color
failed the orange and green pair at 40 and 72 dpi and passed it at 150 and
600. The four context managers were entered in one order at three sites;
_measuring holds that order once. On a figure never drawn they also read
matplotlib's default 0-1 limits and the axes before the layout engine moved
them. On autoscaled lines and a scatter under constrained_layout,
check_series_color passed what audit failed, check_overplotting passed
what it warned on, and check_banking read 1.8x where audit read 1.6x.
A marker outline is seen against what lies round the mark, not under it.
Read at the centres, a line drawn by its own plot along a scatter was ground
for the marks at any width, and one 'o-' line's own stroke never was. So the
two spellings of one page split. Both misreads were in the plot and
scatter spelling: a white halo edge measured as an outline, and an open
marker's only edge passed as a halo. Leaving strokes out of the ground joined
the spellings and split a band drawn as a 20pt line from a fill_between band
23pt across. Read on the rim with strokes and _own_line drawn, 23 of 23
adversarial pairs agree, against 22 with strokes left out, and the verdicts
hold at 100, 200 and 300 dpi. They are own lines from 1 to 12pt under 6pt
marks in both spellings, square, triangle and diamond markers, and a band
drawn both ways; test_marks_on_their_own_line_read_alike_in_both_spellings
and test_a_band_reads_alike_drawn_as_a_wide_line_or_a_fill run them. The
rim is where WCAG 2.2's Understanding 1.4.11 tests a graphical object,
"against adjacent color(s)"; taking its most common colour is this project's
choice. A literature search found no perception study of outlines this thin:
Szafir (2018) tests lines down to 0.05 degrees, and 0.3pt at 50cm is 0.012.
Of the gallery's 83 line and scatter artists, 3 have a _marker_outline_pt
above 0 and 1 reads a ground; of the external corpus's 196, 84 have one above
0 and 3 read a ground. No verdict changes. check_line_weight takes 0.07s on
2x2 panels of 12 outlined 'o-' lines, 0.03s on 20000 outlined marks and 0.17s
on a 6x6 grid of outlined scatters, where drawing every earlier panel under
each one's marks took 0.29s.
The same one-colour ground remained in two places. _ground took the axes'
own facecolor, so under axis("off"), a translucent face or a none-faced
inset a 0.3pt halo edge in the colour under the marks failed the furniture
floor and a visible one passed. A figure-level backdrop drawn before the axes
(fig.add_artist, fig.patches, figimage) read 1.00 ink, and so did one
drawn between two axes: 0.04 and 0.03 in the render. _ground also counted
marks clipped outside the axes, so with most of a scatter outside a small
#333 axes the margin's white won the vote and both halo verdicts inverted;
it rendered once per artist, 36 renders for a 2x2 figure where 4 do. It
also stopped at the axes' patch, so over a black imshow or pcolormesh on a
white face, or an inset with no face over one, a black 0.3pt edge failed as an
outline and a white one passed as a halo. Converting each render to float took
5.8ms of 7.3ms on a 9in figure. A hatched face needed no change. The furniture
colours _foreign_ink matches also take raw facecolors, and the label's own
ground already anchors that test: four layered probes gave detail strings
identical to opaque equivalents, so they are unchanged. Under TkAgg
fig.dpi = MEASURE_DPI resized the window through
set_size_inches(forward=True), its resize event set the figure to 6x4.5in
from 4x3, and each audit grew the next savefig 1.5x, on matplotlib 3.8.4
and 3.11.1. The corpus records no
verdict change.
A code review of the stack found four more. A dashed vlines beside a solid
one was told to separate by dash, which the same lines drawn with plot were
not. A stroke between two vlines hues no longer makes them draw-order
neighbours; that matches plot, and a test pins the two spellings together.
subfig.legend() lands in SubFigure.legends, so a subfigure legend left
check_identity_channel warning "no legend". A line at alpha 0.4 beside bars
graded 0.2, 0.4 and 0.6 lost its level, so four levels read as three. make
sweep over the 25 corpus figures records no verdict change. The diagram in
docs/design.md had lost the two-line diamond
test_the_design_flow_diagram_draws_an_svg reads.
_marks_px read the value under a masked scatter offset, where scatter
draws no mark: all ten offsets of a scatter with five masked. _series_px
did the same, so check_label_attribution counted them as rivals. A
fill(facecolor="none") outline counted as a fill, so graded outlines were
grouped as one level. A text alpha
fades its casing as well as its glyphs, and black text at 0.6 cased in white
over black read 5.7:1 against white where Agg draws 3.8:1.
0.10.0 — 2026-09-30¶
What changed¶
Added¶
check_figure.audit_jsonandcheck_palette.check_json, which returnaudit's andcheck's verdict as a JSON document rather than a printed table.check_figure.AUDIT_SCHEMAandcheck_palette.AUDIT_SCHEMAname the wire format, and both arefigure-gate/audit/1.check_palette.py --jsonprintscheck_json's document instead of the table. The exit code is unchanged.__all__incheck_figure.py,check_palette.pyandsuggest_fixes.py, listing every public module-level name.CITATION.cff, carrying the Zenodo concept DOI10.5281/zenodo.21784217. Itsversionis the sixth site the release bump rewrites.check_figure.load_config,find_configandconfig_keys.load_configassigns thecheck_figureandcheck_paletteconstants named in afigure-gate.toml, or in a[tool.figure-gate]table inpyproject.toml. An integer constant takes a whole number, stored as an int;STYLE_SHEETtakes a string andCONTENT_WIDTH_PTa number.CONFIG_FILENAMES,CONFIG_TABLEandCONFIG_ALIASEShold the two filenames, the table path and the one key that is not a constant,venue.check_figure.py --config, which prints the file found at or above the current directory, the values it sets, and every key this version accepts. Read before the matplotlib import, as--venuesis.- Six rows in
VENUE_WIDTH_PT, taking it from twelve to eighteen:amsart360.0,siam370.38,revtex510.0,revtex-column246.0,beamer-43307.29 andbeamer-169398.34. check_figure.DID_NOT_RUNandsuggest_fixes.DID_NOT_RUN, the prefix a detail carries when the gate could not run.suggestskips a row that carries it.NOT_CONFIGURABLEincheck_figure.pyandcheck_palette.py, naming the uppercase numbers a configuration file may not set and the reason each is not a threshold:MEASURE_DPI,BOLD_WEIGHT_MIN,GRID_PAIR_CAP,RAMP_LUT_NandCMAP_SAMPLES.config_keys()drops from 60 keys to 55, andload_configraises with the reason rather than the "names no threshold" message.- A
doior ano_doifield on every entry ofEXTERNAL_CLAIMSintests/test_prose_claims.py, and three tests over them:test_every_external_claim_carries_a_doi_or_says_why_it_cannot,test_a_cited_doi_is_printed_where_the_reader_isandtest_no_two_claims_cite_the_same_doi. doi:lines on five references that had none: Cleveland & McGill 1984, Cleveland, McGill & McGill 1988 and Heer & Agrawala 2006 inchoosing-a-form.md; Nuñez et al. 2018 and Stone, Szafir & Setlur 2014 instyle-guide.md.
Changed¶
check_style_sheetreturns"warn"rather thanTruewhen nofigure.mplstyleis found. Advisory, sookis unchanged.check_series_colorandcheck_colormapreturn"warn"rather thanTruewhencheck_palette.pyis not importable besidecheck_figure.py. Advisory, sookis unchanged.- All three of those details now open with
DID_NOT_RUN, andsuggestreturns no remedy for a row that carries it. - Nothing a caller could do at 0.9.0 has stopped working.
griffe checkagainst the tag reports one change,VENUE_WIDTH_PT's value, which is the six rows above, and no break incheck_paletteorsuggest_fixes.
Fixed¶
release.yml's TeX install retries attimeout 60andtimeout 240, down from 300 and 600, and no longer sleeps after its last attempt.check_style_sheetwarns on a key the sheet names that matplotlib dropped while parsing, such asgrid.color: #e1e0d9. It returned True for one.- The
scaleargument ofaudit,reportandaudit_json, and the return ofpage_scaleitself, are documented as the ratio they are rather than as a length. Documentation only: no number a gate measures has moved. - The nine authored documentation pages declare a
title:, so the site serves each page's own name instead of its filename: "Commands" rather than "Cli", "How the checkers decide" rather than "Design". The home page and the seven symlinked pages are unchanged. skill/SKILL.mdandskill/references/style-guide.mdname the configuration file. Both sent a reader toCONTENT_WIDTH_PTat the top of a vendored copy and stopped there, which is the one-copy route the file exists to replace, and the skill is what an agent reads. The build snippet callsload_config.- Heer & Agrawala 2006 changed IEEE TVCG
12(4)→12(5), inchoosing-a-form.mdand in theEXTERNAL_CLAIMSentry. The pages, 701-708, were right. - Stone, Szafir & Setlur 2014 changed
2014(1)→22(1)instyle-guide.md, the volume and issue10.2352/CIC.2014.22.1.art00045resolves to. The pages, 253-258, were right. docs/design.mdchanged the stated suite size2190→2256.tests/test_renderer_invariance.pysweeps every gallery figure.BUILDER_NAMESwas a hardcoded eleven under a comment saying it was read off the module; it is parsed fromBUILDERSnow, and the nine figures added since the sweep was written are in it. All twenty hold every row identical across the range.- The dpi sweep's measured cost changed
34rows over eleven figures →76over twenty, incheck_figure.py,docs/design.mdand the sweep's own docstring. The one status flip is stillorbit's ink coverage at 600 dpi. check_palette.oklab_distance,cmap_back_travelandhex_to_linear's raise are exercised. Coverage ofcheck_palette.py86% → 88%.- README
## Try itchanged "The second command prints a failing report" → "check-figureprints a failing report". test_the_readme_names_the_one_command_that_failsandtest_every_source_states_the_real_defect_countadded intests/test_docs_match_code.py.pyyamladded to thedevdependency group, and to theci.ymltestleg that installs cmasher. On a cleanuv sync --group devtests/test_version_sites.pygoes from 13 passed and 6 skipped to 19 passed.test_a_configured_navigation_feature_reaches_the_built_pageandNAVIGATION_MARKUPmoved fromtests/test_docs_site.pytotests/test_docs_render.py, and the four cases now depend onbuilt_site. They skipped in every CI job, and in about half of local-n autoruns.check_type_sizechanged its scale in the detail string from the unrounded float to two decimals, the formatcheck_line_weightalready used.docs/design.mdremoved the claim that the colormap row passes whencheck_palette.pyis not importable, and the "five verdicts" sentence.docs/design.mdchanged "without a Python interpreter on PATH" → "with a bare Python interpreter and nothing installed".docs/gallery.mdchanged the heading "The figure the checker is supposed to fail" → "The self-test, and the demo", and "The only bar chart" → "The only bar chart on Cartesian axes".docs/compatibility.mdchanged what sets the 3.11 floor to nameload_config, and removed the paragraph repeating the two floors.docs/install.md,docs/how-to.mdanddocs/api.mdremoved copies of the import-line history, thepy.typednote, thesuggest_fixes.pynote and the "default route" claim, and link to the one copy that stays.choosing-a-form.mdchanged "a sevenfold difference" → "one bar eight times the length of the other, for values 7% apart", "the onecheck_figure.pyfails" → "one of the three", "task 2/3" → "rank 2/3", and "Color sits at the bottom" → "Color saturation sits at the bottom, and hue is off the list".choosing-a-form.mdandstyle-guide.mdremoved transparency as a fix for overplotting;test_transparency_does_not_move_the_overplotting_rowadded.style-guide.mdchanged the Fast path's and Procedure'scheck_figure.pystep →report(fig), the adjacent CVD figure32.0→32.0 at dichromacy and 31.7 at the worst severity the gate reports, and the sub-35% placement sentence → "prints a 10pt label under 3.5pt". Removed "the one figure in this repository that uses a legend".SKILL.mdSetup addedsuggest_fixes.pyto the copy step, changed "it only sets the type floor" → "the error moves the measured type and stroke sizes by the same 5%", and "nearly all of them matplotlib" → "matplotlib was the most-imported charting library among them".CONTRIBUTING.mdchanged "mypy runs unannotated" → "mypy runs with the strict flags off", and "Changing a threshold" → namestests/test_thresholds_are_constants.pyanddocs/gates.mdbesidetests/test_palette.py.zensical.tomladdedfavicon = "images/favicon.png", a 64pxlucide/fencein#0072b2, and[project.theme.icon.admonition]notelucide/paperclip→lucide/pencil-line.
Why it changed¶
A release retry loop longer than its job¶
release.yml's test job is bounded at 20 minutes, and its TeX retry loop
could take 3 x (300 + 600) seconds plus 90 of sleeps, 2790 in all. A stalled
mirror would have been cancelled mid-loop, before the loop's ::error::
line ran: the defect pgf in ci.yml was already fixed for. The loop now
uses pgf's budget, 945 seconds, and
test_a_retry_loop_fits_inside_its_job holds every retry loop to its job.
A hashed colour the style-sheet row could not see¶
check_style_sheet's docstring said it caught a colour written with a
leading #. It compared the values matplotlib parsed from the sheet with the
live rcParams, and # starts a comment in an mplstyle, so
grid.color: #e1e0d9 parses to no value and the key is dropped. The sheet
and the live rcParams then agree on its absence: a sheet carrying that line
returned (True, 'all 1 keys match'). The row now also reads the keys off
the file's text. test_style_sheet_row_notices_a_color_written_with_a_hash
pins it.
SKILL.md and CONTRIBUTING.md against the code¶
SKILL.md step 6 uses report(fig, suggest=True), which prints nothing extra
without the file its Setup never copied. CONTENT_WIDTH_PT scales the line-weight
gate through the same page_scale as the type gate. Potluri et al. report
matplotlib as the most-imported charting library, not as the source of nearly
every image. pyproject.toml's own mypy comment says every function in
skill/scripts is annotated. The value of every threshold is pinned in
tests/test_thresholds_are_constants.py, which the old sentence did not name.
The two references against the code¶
check_overplotting reads offsets and sizes, and
test_the_overplotting_remedy_does_not_advise_transparency already held the
remedy to that, while both references still offered transparency first. Bars
101 and 108 on a baseline of 100 are 1 and 8 long. check_figure.py with no
arguments runs the self-test, so the Fast path's validate step never audited the
reader's figure. The gate prints 31.7 for the shipped cycle, so a reader
checking the guide's 32.0 against it found a mismatch. examples/gallery.py
calls legend at four sites. A figure's label size under a small placement
depends on the size it was authored at, which "every label at or below 6pt" left
out.
A docs pass for claims the code no longer backs¶
check_colormap warns without check_palette.py (check_figure.py:4523), so
the design page contradicted its own "WARN is not FAIL" note. One status flip
over five resolutions is two verdicts, not five. check_palette.py runs under
Python, so it cannot run without an interpreter. The wind rose at
examples/gallery.py:1172 is also a bar chart, and the image under the old
heading is the demo, which passes. The tutorial printed
scale 0.44164444444444445 beside a Line weight row reading scale 0.44.
The README's first claim was about the wrong command¶
The second command in ## Try it is check-palette, which passes on the three
hexes the README gives it. The test runs every command in that block and
requires the one that prints [FAIL] to be the one the sentence names.
A number in capitals is not always a threshold¶
_config_targets selects by shape, which is what keeps it from falling behind a
threshold added tomorrow. Shape cannot tell a floor from the frame the floors
are measured in. MEASURE_DPI is a float named in capitals like every
threshold, and a file setting it would rescale every pixel threshold in
check_figure at once while each threshold's value stayed where a reader could
see it, which is the failure MEASURE_DPI was added to close.
tests/test_thresholds_are_constants.py already drew this distinction in its
NOT_A_THRESHOLD ledger. The config surface did not read it.
Five constants, each with the reason in the module beside it. A raise rather than a silent skip, for the reason an unknown key already raises: a threshold quietly ignored leaves a project believing it raised a floor. A different message, because "names no threshold" sends a reader to check their spelling and the spelling is right.
check_palette.py carries its own list. These files are vendored one at a time,
so a contract between two of them cannot live in an import either may lack, and
that file reads no TOML anyway: tomllib arrived in 3.11 and CI holds it to 3.8.
A citation the prose gates could not check¶
EXTERNAL_CLAIMS held every external claim to a source, a dated verification
and a quote, and three tests over it. None of them could see a wrong citation.
test_an_external_source_is_named_in_the_references asserts the first surname
appears in the document, so "Heer" satisfied it whatever the volume said, and
choosing-a-form.md gave Heer & Agrawala as IEEE TVCG 12(4) for as long as the
entry existed. The paper is 12(5). It was the one reference in either section
carrying no DOI.
So a deposited work is now cited by identifier, and the identifier is printed
where the reader is. Resolving it catches a wrong volume, issue, page or year,
which no string comparison in this file can. The lookup is the reader's: nothing
in the suite reaches the network, and a claim whose source has no DOI, such as a
publisher's instructions-for-authors page or a file in the LaTeX2e kernel, says
so in no_doi rather than leaving the field empty. An absent identifier is
otherwise indistinguishable from an oversight, which is how this one survived.
The third test rejects two entries sharing one DOI. The wrong issue number came from a neighbouring entry; copying the identifier too is the same slip, one field further along.
One set of thresholds a group can agree on¶
The two documented ways to move a threshold are to edit a vendored copy and to
assign the global before calling audit. Both are one person's copy, and
docs/how-to.md names what the second costs: a threshold moved in one test file
is a figure that passes locally and fails in CI. More than one author on one
document had nowhere to write the floor down once.
A file is read only when something calls load_config. Reading one on import
would move a threshold the caller never named, in a project that keeps every
threshold visible as a constant.
A key naming no constant raises, and the message lists what is accepted. A misspelled threshold that is quietly skipped leaves a project believing it raised a floor. Every key is checked before any is assigned, so a file with one bad key changes nothing.
Settable keys are computed from the modules, so a threshold added to either one
is settable the day it lands. Numeric constants only, plus CONTENT_WIDTH_PT,
STYLE_SHEET and venue. AUDIT_SCHEMA is a wire format and DRAW_RC_ATTR is
an attribute name: a file that could reach those could rename the JSON contract
from TOML.
check_palette.py reads no TOML. tomllib arrived in 3.11 and CI runs that file
on 3.8, so check_figure reads the file and sets the palette constants through
the sibling import it already has.
Six venues measured, not copied¶
Six of the twelve rows were machine-learning conference styles; the rest were
IEEE, Nature and bare article. A mathematician had no row. amsart and SIAM's
class carry most of that work, revtex4-2 is what APS asks for, and
skill/SKILL.md claims slides and lecture decks as targets against no slide
width at all. docs/how-to.md used SIAM as its worked example of raising a
threshold while the table did not know SIAM's width.
The six were measured, not looked up: on TeX Live 2026, by typesetting an empty
document in each class and reading \the\textwidth out of the log. That is the
procedure the table's comment demands of a reader. Each row names the class
version the log reported, because a width is a property of that version and
style files get revised between years. siamart220329.cls is not in TeX Live; it
came from SIAM's own macro distribution.
amsart and siam are one-column classes, so their \columnwidth equals their
\textwidth and is not listed twice. revtex carries its column because APS
reprint is two-column.
A row that could not run is not a row that passed¶
Three gates reported a pass for having checked nothing. check_style_sheet
passed when it found no figure.mplstyle, which is exactly the figure it exists
to catch: one drawn with plt.style.use forgotten. The inconsistency was
visible in the suite, where a STYLE_SHEET pointing at a missing file has
warned since 0.1.4 and no sheet at all passed. check_series_color and
check_colormap passed when check_palette.py was not importable beside them,
which is the vendored copy that took one file and ignored the install page's
warning: the only colour checks in the file, switched off, reported green.
All three are warns rather than hard failures. A copy that deliberately left the
palette module out is doing correct work, and a missing style sheet is not a
defect in the figure. What was wrong was the status, not the severity: ok turns
on hard False only, so no build that passed before fails now, and the row says
which check did not run.
check_series_color and check_colormap are not advisory and still fail on what
they measure, so the count in ADVISORY_GATES is unchanged at eight. Three rows
can now both fail and warn where Type size was the only one.
Turning three passes into warns routed them somewhere they had never been.
suggest offers a remedy for every row that is not passing, and all three gates
have one: a row that did not run was answered with "apply the sheet where the
figure is drawn, inside the same rc_context" when there is no sheet, and "use a
ramp whose lightness runs one way" when nothing was classified. Gate name cannot
tell the cases apart, because the style-sheet gate's other warn does want that
remedy. So the detail says which it is. DID_NOT_RUN is a prefix, suggest
skips a row that opens with it, and each of those rows already carries the right
action in its own [FIX] clause. Both files spell the string out rather than
share it through an import: suggest_fixes.py is the optional third file and
cannot require the module it describes, so a test asserts the two copies agree,
as one does for AUDIT_SCHEMA across the two checkers.
A verdict a build can read¶
report prints a table for a person and audit returns tuples for Python. A CI
step that wanted the rows had neither: parsing the table means depending on a
layout that is there to be read, and calling audit means the build is a Python
program. audit_json and check_json are the third route, and they serialise
the object the checker already computed rather than re-measuring, so the three
cannot disagree about one figure.
Both documents carry the inputs, not only the verdict. A figure that passes at
venue="neurips" and fails at icml-column is one figure and two true answers,
and the same eight hexes pass on white and fail on a tinted page. A stored
artifact recording only ok is one nobody can reproduce a month later, which is
the failure a CI artifact exists to prevent.
status is spelled pass, fail or warn rather than carrying the tuple API's
True, False and "warn". One JSON field holding a bool for two cases and a
string for the third is a shape every consumer would have to learn, and ok is
already the bool worth branching on.
check_palette.py gained one import to do this, json, which is in the standard
library. The file's claim to import nothing else is what makes it vendorable into
a non-Python toolchain, and --json did not cost it.
There is no --json on check_figure.py, because that command audits no figure
of yours: run with no arguments it self-tests on a deliberately broken figure.
The equivalent is audit_json in the API.
The title a reader sees before the page¶
Zensical titles a page from its filename. Not from its # heading, and not
from the nav label: cli.md served as "Cli - figure-gate" with # Commands in
the file and "Commands" in the nav, design.md as "Design" against "How the
checkers decide". Every page on the site was serving a slug, in the browser tab,
the search result and the link preview.
title: front matter is what the theme reads, and only the nine authored pages
can carry it. The other seven are symlinks; front matter in their targets would
surface in the README on PyPI and in the style guide a reader vendors. The home
page keeps its filename's title for that reason. Two tests hold one half each:
that a page writes its name down, and that the site serves it under that name.
A scale that was documented as a length¶
page_scale returns width * placed_frac / (fig.get_size_inches()[0] * 72),
which divides points by points. Four docstrings named a unit for it anyway,
larger than the real number by 72. A reader who passed scale= as that unit
would certify every figure at 72 times the size it prints at.
The correction is in the wording alone. docs/design.md had it right, and so
did audit_json's own paragraph two lines above the Args: entry that
contradicted it. The retired sentence is now an entry in
tests/test_prose_claims.py's retraction ledger, which sweeps the documents and
both modules, so it cannot be copied back.
One definition of public¶
griffe reads __all__ when a module declares one, and
skill/scripts/audit_api.py runs griffe check against the last tag on every
pull request. So an __all__ that omitted a name would not merely mislead a
reader about the public surface: it would narrow what the API gate compares, and
a break in the omitted name would stop being reported at all. The lists are
therefore exhaustive, and
tests/test_api_reference.py::test_all_is_the_whole_public_surface regenerates
each one from the module's own top level and fails on any disagreement. The gate
was run against v0.9.0 with the lists in place and reports the same surface it
reported without them, which is the evidence that nothing went quiet.
A citation, and the floor it does not move¶
CITATION.cff carries the concept DOI rather than a per-version one. Zenodo
mints a fresh number on each deposit, so a per-version DOI cannot be derived from
the version and cannot be a bump site; a citation carrying one sends every future
reader to whichever release was current when the line was written. date-released
is absent for the same reason, and
tests/test_version_sites.py::test_the_citation_carries_no_date_released is what
keeps that a decision rather than an oversight.
Those six tests ran nowhere but a contributor's machine. yaml was in no
declared group; it reached the local environment as a transitive dependency of
the docs group's MkDocs tree, and pytest.importorskip turned its absence into
a skip rather than an error. A clean uv sync --group dev gave 13 passed and 6
skipped, and ci.yml's test matrix installs only pytest, xdist and matplotlib,
so it skipped them too. So the newest version site had the parametrised pattern
test watching its shape and nothing at all checking it was still a citation: not
the DOI, not the author, not the version a reader resolves. pyyaml is named in
dev now, for the same reason api names griffe outright instead of taking it
from docs: a group that gets its tool by accident from another group's tree
stops working the day that tree changes.
The importorskip in citation() stays. A plain import yaml fails collection
on every test leg, and the count docs/design.md states with it. One test
leg installs PyYAML, so the six run in CI.
Looking for the same shape elsewhere found four more.
test_a_configured_navigation_feature_reaches_the_built_page reads
site/gates/index.html and skipped when it was absent, which was every CI job:
the only one that builds a site is the docs workflow's and it ran
tests/test_docs_render.py alone, while ci.yml syncs --group dev and carries
no zensical. So a navigation feature could stop reaching the theme's markup and
the four cases watching for it would report nothing.
Locally it was worse than absent. built_site cleans and rewrites the one
site/ a checkout has, and this test read that directory without taking the
fixture, so under -n auto it opened a path another worker was replacing: two
isolated runs back to back gave 53 skips and then 57, for a site that existed
before and after both. The test and NAVIGATION_MARKUP are in
test_docs_render.py now and depend on built_site, which is the coordination
and also why the docs workflow already runs them. A test that reads a directory
another test rewrites has to take the fixture that owns it.
The Python floor stays at 3.11. SPEC 0 recommends dropping a release about three
years after it ships, and by that calendar 3.11 was due to go in April 2026.
Nothing here uses a 3.12 feature, so raising the floor would remove users and
change no line of the checkers; what the floor is actually set by is tomllib,
which arrived in 3.11. docs/compatibility.md now says so, because a floor that
looks overdue and is not is a question a reader should not have to ask twice.
The site's icons¶
The browser tab showed the theme's stock favicon while the header showed the
fence, so the favicon is now the fence. Nine call-outs are note, which the
modern variant draws as a paperclip; the classic variant draws it as
material/pencil-circle, and lucide/pencil-line is that glyph in Lucide's
stroke.
0.9.0 — 2026-09-09¶
What changed¶
Changed¶
audit(context_axes),audit(venue),report(context_axes),report(venue)andreport(suggest)changed to keyword-only.check_figure.auditmeasures under the rcParams the figure's first audit saw.METRIC_RC_KEYSnames them.Style sheetand the Type 3 clause ofFontsstill read the live rcParams.Line weight,Colormap kind,Contrast stack,Form,Mark ratio,Series color,Overplotting,Ink coverage,Contour dashandBankingwalk child axes. Content insideax.inset_axesis judged where it went unjudged before, so a figure carrying one can newly fail or warn.check_figure._all_axesreturnsfig.axesfirst and descendants after, so theax{i}names in the detail strings keep their meaning for the panels that were already numbered.Line weightmeasures spines and gridlines, major and minor, againstFURNITURE_FLOOR_PT(0.5pt) rather than skipping them. A floor of zero is not "a lower floor". Tick marks remain unmeasured: the sheet does not author their width, so judging a default reports the library rather than the figure.
Added¶
check_palette.cmap_kind_rgbandcheck_palette.cmap_back_travel_rgb, classifying a ramp from float sRGB. The hex-takingcmap_kindandcmap_back_travelare unchanged.- Two gallery figures,
gallery-calloutandgallery-secondary-scale, carrying an annotation drawn with a leader line and a secondary axis. - Six gallery figures,
gallery-survival,gallery-raster,gallery-rose,gallery-parity,gallery-phaseandgallery-trendmap: a Kaplan-Meier staircase, a spike raster, a polar rose, a parity plot, boundaries labelled along themselves, and a field faded by its own significance. The corpus is nineteen figures. examples/gallery.pyaudits the sheet's own palette withcheck_palette, categorical and ordinal, alongside the figures.mainfails on a palette row as it does on a figure.check_figure.MARK_RIDE_TOL_PXandcheck_figure.MARK_RIDE_FRAC_MIN, the two thresholds separating a companion mark from a rival series.check_figure.RAMP_LUT_N,check_figure.RAMP_CHANNEL_TOL,check_figure.RAMP_SPACING_TOLandcheck_figure.RAMP_MIN_STEPS, the four values deciding whether a panel's colours are samples of a registered ramp.check_figure.FORM_BAR_MIN_PATCHESandcheck_figure.FORM_BAR_BASELINE_TOL, the two values deciding whether a run of rectangles standing on one edge is a bar chart.check_figure.MATH_SCRIPT_FLOOR_PT, the type floor for a mathtext sub- or superscript, which is lower than the floor for body text and sourced separately.tests/test_style_context_invariance.py, holding every row identical across the sheet boundary fordemoandencoding.check_figure.marker_extent_pt, the width and height in points that aplotmarker actually draws, which is notmarkersizefor every marker.check_figure.marker_stroke_ptandcheck_figure.collection_stroke_pt, the stroke aplotmarker and ascattereach actually lay down around a mark, which is zero whenever the edge is not drawn at all.check_figure.bars_rest_on_a_shared_edge, whether a panel's bars stand on one edge or each carry their own offset, which is what separates a bar chart from a Gantt chart or a waterfall.check_figure.MARK_ORNAMENT_GAP, the factor by which the largest mark has to exceed the next largest before it reads as an ornament rather than as the top of a graded run. It picks the remedy, not the verdict.check_figure.ALPHA_RAMP_MIN_STEPS, the number of distinct non-opaque alphas on overlapping fills of one colour at which the run reads as one interval encoding rather than as that many separate decisions.REMEDIES(suggest_fixes) gains a secondMark ratioentry, for the case where the sizes are graded and clipping them would flatten an encoding. The existing clip entry keeps its code and its position; its suggestion text now says which case it is for and what it costs. A caller readingREMEDIESby index rather than bygatesees the row move.- A twentieth gallery figure,
gallery-broadening: a spectrum whose inset carries four curves of its own, sampled off an ordered ramp, over two panels stacked on one x scale. The corpus is twenty figures.
Fixed¶
Contrast stackno longer fails a figure that uses matplotlib's per-point alpha. An alpha ramp counts as one level.Text collision,Label attributionandText readabilitymeasure a callout's string rather than its leader line.Label attributionreads an annotation at the anchor its leader points to, rather than at the string. A leader drawn to the wrong curve still fails.Label attributionno longer judges a panel title, axis label or colorbar label as a direct label.Axis redundancyrequires the panels to share limits, scale type and axis title before it calls a tick column repeated.Clippingrecognises off-view ticks on a child axes, sosecondary_xaxisandsecondary_yaxisno longer report them as clipped text.Colormap kindclassifies a ramp before the 8-bit round trip.Colormap kindrecognises a colormap the author evaluated themselves. Series drawn in colours sampled offjet,rainbowor another map a reader cannot order now fail the row, where before no artist carried an array and nothing on the figure looked at the ramp at all.Formreads bars drawn as plainRectanglepatches. A truncated baseline built by hand rather than byax.barnow fails the row, and the two spellings return the same detail string.Axis redundancymeasures the x direction. A column of panels repeating its tick row now fails the row as a row of panels repeating its tick column already did, under the same shared-scale requirement. Figures with stacked panels on one x scale and nosharexcan newly fail. The detail namesrepeated x tick rowbeside the existingrepeated y tick column.Line weightmeasures patch edges and annotation arrows. A schematic drawn entirely out of boxes and arrows was reported as having no strokes at all, and its hairlines can newly fail. Spines and tick marks are still not measured, deliberately.Type sizemeasures mathtext sub- and superscripts rather than reading the declared size, and holds them toMATH_SCRIPT_FLOOR_PTrather than toTYPE_FLOOR_PT. A figure with a script nested more than two deep can newly fail. A first-level script is unaffected, which is what keeps the row off matplotlib's own log-axis tick labels.usetexfigures are exempt.Overplottingreads a cloud drawn asplotmarkers with no connecting line, not only one drawn byscatter. The two spellings of the same cloud now report the same number. Figures using theplotspelling can newly warn, and two in this project's own corpus do. The detail namesax{i}.line{j}beside the existingax{i}.col{j}.- Auditing one figure twice returns one verdict, and a gate called on its own
reports what
auditreports. audit_api.pymatches a reported name with lookarounds rather than\b, so a parameter change can be written down at all.Line weightno longer raises TypeError on anEventCollection, which reports one linewidth where every other collection reports a sequence. A raising non-advisory gate is a hard fail, so a spike raster failed on a defect in the checker.Label attributionno longer counts a series' own companion marks as a rival. Censoring ticks drawn along a survival curve sit 0px from it by construction, so no placement of a direct label could clear them.docs/imagescarries the eight figures this cycle added to the corpus.gates.mdcarries the rule and not the argument, which its own intro already routes to the style guide. SixFails whencells and two remedy cells drop the rationale they had grown; it lands on the pages that own it, where none of it existed: the gridline-as-ink exemption and the white-on-white contrast case under the style guide's "Text on fills", the three-alpha budget beside the composition bullet it qualifies, the reverse ramp lookup under "hand the ramp to a colormap", and the Gantt and waterfall baselines underchoosing-a-form.md's baseline section. No heading moved, so no link breaks.- The home page's card icons render at 1.5rem. They are inline
<svg>with a viewBox and no width or height, which SVG defaults to 100%, so each one had been taking the full width of its card. - The release bump no longer requires
^## Unreleased$on the bump that opens the next development cycle.exclude_bumpson that entry; the release bump still refuses to run without notes. uv.lockis a bump entry, anchored across itsnameandversionlines.Series colorno longer reads an inset-zoom connector as a data hue.indicate_inset_zoombuilds its connectors out ofConnectionPatch, and matplotlib gives each a facecolor off the property cycle although the shape it draws is a line._data_colors_by_axesexcludes them.gallery-broadeningsets its connectors' width itself.lw=onindicate_inset_zoomreaches the indicator rectangle and, on matplotlib 3.8, not the connectors.test_a_two_line_label_carrying_mathtext_parses_per_linenames the warning it guards against instead of raising on every warning.- The macOS CI leg runs pytest at
-n 2rather than-n auto. Label attributionreads a stroke-lessLine2Das marks rather than as a polyline.check_figure._series_pxsends one to_marks_px, so a cloud drawn asplot(..., linestyle="none", marker=...)is no longer measured along chords the figure never drew. A label that read as ambiguous only against those chords now passes.Overplottinganswers a large cloud without scipy installed. The scipy-free branch of_contact_fractionenumerated every pair as a dense matrix, which ongallery.orbit's 168000 marks is 226GB; it walks a uniform grid now, over the same radius-octave grouping the scipy path uses, for the same answer.
Why it changed¶
The declared floor is a different checker, and nothing on this branch had been run against it. CI carries matplotlib 3.8.4 on one leg and every local run used the current release, so twenty-one commits went up green and came back with three failures the developer machine cannot produce. All three are worth writing down because none of them is a version guard in a gate.
indicate_inset_zoom is the whole story for two of them. It returns a
rectangle and four ConnectionPatch connectors, and on 3.8 the lw= given to
it reaches the rectangle only: the connectors keep patch.linewidth, which
this sheet ships at 0.7. They also carry a facecolor off the property cycle,
#E69F00, although a connector draws a line and fills nothing. On the current
release neither is visible to the gates, because the connectors are not in
ax.patches at all.
Those two failures needed opposite answers, which is the part worth keeping.
Series color counting #E69F00 as a fifth data hue against the four viridis
samples the panel encodes with is a checker defect: a connector carries no
identity, and no reader is being asked to tell it from a series. Line weight
reporting a 0.70pt stroke is not a defect. The stroke is drawn, the row's own
docstring says patch edges are data, and the author had asked for 1.0 and
silently not got it. So the checker changed on the colour and the figure
changed on the width, and treating them alike in either direction would have
been wrong once.
Corpus exposure, since a clean sweep proves nothing without it: 21 figures, 0
verdict changes, and on the current release 0 of 20 gallery figures carry a
reachable ConnectionPatch at all. The sweep was exposed to nothing and could
not have moved. On 3.8.4 exactly one figure carries them, four connectors of
which two are visible. The evidence here is the adversarial test and the full
suite run against the floor, not the sweep.
The mathtext failure was a test measuring its dependencies. It asserted a
measurement under a blanket warnings.simplefilter("error"); on 3.8.4 the
parse reaches _fontconfig_pattern, which calls pyparsing's deprecated
parseString and resetCache, and _script_min_pt turns any exception into
None deliberately, so the row reported no measurement and the test read
None == 3.773. The parse itself is identical on both versions, glyphs at
3.773, 5.39, 7.7 and 11.0pt. The filter now names the U+000A warning the test
exists to catch.
The macOS leg was killed, and the reason was not the one it looked like.
Three processes died at once, returncode -9 with the buffered stdout lost
and two xdist workers reported node down: Not properly terminated, which
reads like a leak. It is not. Holding the whole built corpus costs 135 MB and
the module that caches it was the obvious suspect and the wrong one; the cost
is in audit, where one pass over gallery-orbit's 4000-point band takes
530 MB for its canvases, KD-trees and pixel blocks. test_renderer_invariance
is parametrised over all twenty builders, so -n auto on the arm64
macos-latest image gives three workers a heavy figure each, at ~600 MB
apiece, beside test_example.py running the entire gallery in a subprocess.
That image carries 3 cores and 7 GB against ubuntu's 4 and 16, which is why
this leg alone fails and why it passed until the corpus grew. Two workers is a
cap on concurrency, not a repair: nothing here leaks, and the figures are
closed where they are built.
Ten rows were not looking at insets, and the suite could not have told
anyone. ax.inset_axes and secondary_xaxis/secondary_yaxis are added
through add_child_axes and never reach fig.axes, so a gate that walked
fig.axes audited the host and skipped the child. Moving one piece of content
from a panel into an inset and re-reading every row is what measured it: a
0.15pt hairline, a jet heatmap, six alpha levels, a pie, a size-encoded
scatter, nine hues, a 4000-point cloud, a saturated raster, undashed contours
and a sine banked to 85 degrees all passed inside the inset and failed outside
it. Ten rows, one construct.
The route matters and is easy to get wrong.
mpl_toolkits.axes_grid1.inset_locator.inset_axes goes through add_axes and
was always visible; ax.inset_axes is the blind one, and it is the idiom
matplotlib has documented since 3.0. A sweep written against the first route
finds nothing and concludes there is nothing.
This adds fires rather than removing them, so it was measured against the
corpus before it shipped: the nineteen gallery builders plus demo.build,
twenty figures, swept on main and on the branch and diffed row by row. No
verdict moved and no detail string moved. That is the right answer and it is
also weak evidence, for the reason the whole defect exists: the corpus has no
figure with a data-carrying child axes, so it had nothing to move. The thirteen
tests are where the construct actually lives, and eleven of them fail on the
commit before this one.
jet escaped the checker entirely by being evaluated one step at a time.
Six series drawn color=cmap(i / 5) off jet passed every row on the figure:
no artist carries an array, so Colormap kind found nothing to classify, and
six hues sit under the eight Series color allows. The rule was already
written down - _data_colors_by_axes says in its own docstring to draw an
ordinal ramp as c=values, cmap=... and "never as a pre-evaluated RGBA list" -
and nothing enforced it.
It is caught by reverse lookup rather than by classification, and the
difference is the whole difficulty. Handing the panel's drawn hues to
cmap_kind_rgb would condemn every categorical palette, Okabe-Ito included: a
set of hues chosen to be told apart is not ordered in lightness and was never
meant to be. So the narrow question is asked instead - are these colours evenly
spaced samples of a registered map a reader cannot order - against the
sixteen such maps matplotlib ships, each in both directions.
The first draft failed Okabe-Ito. Over 256 samples tab10, Set2, Dark2 and
this project's own registered okabe_ito all classify misc, for the same
reason a categorical palette should, and matching against them made drawing
series in Okabe-Ito fail the row. Inheriting the CMAP_QUALITATIVE_N split the
qualitative branch already makes is what excludes them, and the control test
pins it.
RAMP_MIN_STEPS = 3 is measured, not chosen. Two colours make one step and one
step is evenly spaced by definition, so at two the check asks only whether both
hues sit somewhere on some ramp: 17 of 4000 pairs drawn from an
Okabe-Ito/tab10/Set2/Dark2 pool matched. At three, those same 4000 draws
matched nothing, and neither did 4000 uniform-random sRGB palettes at any size
from three to six. The discriminating test turns out to be the 3/255 channel
tolerance rather than the spacing one - a ramp is a curve through a cube, and
little lands on one by accident - which is also why the drawn order is not
required.
The corpus sweep is clean, and it is thin. Twenty figures, no verdict changes, no detail-string changes; but only two of the twenty panels carrying series colours have three or more distinct ones, so the check was exposed to two panels rather than twenty. The corpus draws one or two series per panel almost everywhere. The 8000-palette measurement above is the real over-fire evidence here, and the sweep only confirms nothing already published moved.
A bar chart drawn by hand carried a truncated baseline straight through.
Form read ax.containers for a BarContainer and nothing else, so the same
chart built from ax.add_patch(Rectangle(...)) reported no pie, no 3D, no
truncated bar baseline. Both spellings now return the same detail string,
which is the test that states the defect directly.
Reading rectangles as bars is easy to get wrong in the over-firing direction,
so the constraints are narrow: the exact Rectangle type, drawn in data space,
unrotated, standing on a shared edge, and varying in length along the other
axis. Each one closes something specific. axvspan and axhspan are
Rectangles, and a pair of shaded bands shares an edge and varies in extent,
which is every other test here; they are drawn in a blended transform, so
get_data_transform() separates them and a test pins that rather than assuming
it. Equal length excludes a rug and a single-row heatmap, neither of which says
anything with length.
The shared edge is the modal one rather than a unanimous one, so a stacked chart is read by its bottom row. On its own that was too loose: a four-step waterfall had two segments land on the same edge by arithmetic and was read as a two-bar chart. So anything off the modal edge has to rest on the top of another rectangle in its own column, which is what stacking is and what floating is not. That also keeps the gate off the offset baselines that are an open argument in this project rather than a settled defect, since deciding that argument by arithmetic accident would be the wrong answer twice over.
The corpus could not have found any of this. Twenty figures swept, no verdict
changes; but only two panels carry a bar at all and both carry a
BarContainer, which is matched first, so the new route was exercised by zero
corpus panels. A fourteen-case adversarial set is what the constraints were
measured against, and it is where the waterfall false positive was found. It
ships as twelve tests.
Half of Axis redundancy was measuring nothing. The tick-duplication test
looped over row groups only, so a row of panels repeating a y tick column
failed and the identical figure rotated, a column of panels repeating an x tick
row, passed. Two stacked panels on one x scale printed the same run of numbers
twice and the gate said the furniture was not duplicated.
No documentation changed, and that is the finding rather than a convenience.
docs/gates.md has said this row fires when "panels sharing limits, scale type
and axis title repeat tick labels or axis titles", naming no direction, so the
page has been describing the fixed behaviour the whole time and the code was
the half that was wrong. Nothing in the suite could tell, because a claim about
both directions is satisfied by a gate that measures one.
The x direction inherits the shared-scale requirement rather than re-deciding
it. That requirement was added in the round before this one, and reading tick
strings alone told two panels carrying kilometres and seconds to use sharex,
which would put unrelated data on one axis.
It found a real fire in the suite's own fixtures. The row-spanning mosaic test
stacks two panels on an identical x scale with no sharex, which is exactly
the defect, and it had gone unnoticed because nothing looked. That fixture now
names two distinct x quantities so the test measures the spanning panel it is
about, and the fire it was tripping is described here rather than sanded off.
Corpus: no verdict changes, and one figure of the twenty is exposed.
gallery-small-multiples is the only one with a column of two or more panels,
and it uses sharex, so its upper tick labels are hidden and the visible
strings differ. That is thin, but the one exposed figure is the canonical
correct case, which is the one worth not breaking.
Line weight was silent on the figure whose every stroke was the defect.
It read ax.lines and ax.collections, and a schematic is boxes and arrows
and no Line2D at all, so one drawn wholly at 0.15pt returned no strokes to
measure.
What to add was decided by measuring the corpus first rather than by argument, because this row was expected to fire on almost everything. Counting every stroke the gate could reach, on twenty figures: patch edges, 20 strokes on 2 figures, none under the floor. Annotation arrows, 5 strokes on 2 figures, none under. Tick marks, 377 strokes on 19 figures, none under. Spines, 57 strokes on all twenty figures, every one of them under the floor, because the sheet ships the axis rule at 0.72 to 0.8pt on purpose.
So the item split in two on the evidence. Patch edges and arrows are data ink
and cost nothing to start measuring. Spines are furniture, and adding them
would fail the entire corpus, which is the data floor failing the sheet's own
design: exactly what the row's docstring has always said it must not do. They
stay out, and a test pins that as a decision rather than leaving it as an
absence. Tick marks stay out too; they fire on nothing here, but they carry an
open disagreement with check_svg, whose own corpus pins ten of thirteen fires
on tick marks, and settling that by side effect would overturn a pinned
measurement.
Three detail strings moved on the corpus and no verdict did, which is the
change working rather than noise: gallery-rose went from no strokes to
measure to sixteen strokes, gallery-schematic from one to nine, and
gallery-callout from one to two. Real content the gate had been blind to, all
of it above the floor.
Furniture had no floor, and the docstring's claim that it had a lower one was
false. The old code skipped spines and gridlines entirely, which is a floor
of zero, and a floor of zero is not "a lower floor". Measured on the corpus:
all 982 furniture strokes on twenty-one figures are under LINE_FLOOR_PT, and
every one clears 0.5pt, the thinnest at 0.63pt. The sheet ships the axis rule
at 0.8pt and the grid at 0.7pt on purpose; measuring them against the data
floor would have failed the corpus on the sheet's own design.
Science's instructions give "a minimum of 0.5 point at the final reduced size"
for line widths, which is both lower than SIAM's number and stated against the
figure's placed size. FURNITURE_FLOOR_PT = 0.5 is that number, measured
through page_scale the same way LINE_FLOOR_PT is. The two floors are two
sources because they cost the reader different things: a gridline that drops
out costs a reference, and a data curve that drops out costs the finding.
The headroom is thinner than the data row's. The sheet's spine is 0.8pt against a 0.5pt floor (ratio 1.6), the same as a 1.6pt data line against 1.0pt, so those two fire at the same placement. The grid is the tight one: 0.7pt against 0.5pt (ratio 1.4), so between placement scale 0.625 and 0.714 the grid fires while the data passes. That is the gate correctly saying the reference will drop out before the finding does.
The minor grid is read off the minor ticks rather than from the axis, which hands back the major gridlines alone. A minor grid is authored the same way and drops out at the printer the same way, so reading only the majors would have left half the grid at the floor of zero this entry is about. No corpus figure draws one, so this is a gap closed by construction rather than by measurement.
The fixture collision exposed by the full suite is the concrete case.
test_a_bar_with_no_edge_is_not_a_hairline audits at scale=0.5, and the
sheet's default 0.8pt axis rule prints at 0.40pt there, under the furniture
floor. That is a true fire about a different stroke, and it masked the patch
edge the test is about. Fixed by setting that fixture's spines to 1.2pt, with
a comment saying why the half scale has to stay. The gate was right; the
fixture conflated two questions.
A 3.77pt glyph cleared a 7.5pt floor, and the obvious fix failed the corpus.
Mathtext draws each script level at 0.7 of the level above, so $x_{i_{j_{k}}}$
set at a nominal 11pt puts a k on the page at 3.77pt while get_fontsize()
reports 11.0 for the whole string.
Measuring it is easy: matplotlib's parser returns one entry per glyph carrying
the size that glyph is set at, so nothing here has to know the shrink factor,
and the result is dpi-independent. Doing only that, and judging every glyph
against TYPE_FLOOR_PT, sent three of the twenty corpus figures to a hard fail.
Two of the three were failed on $\mathdefault{10^{-11}}$, which is
matplotlib's own log-axis tick label. No author wrote it, and the row's advice,
"cut words, do not shrink type", cannot be acted on against it.
That was the row being wrong rather than the corpus being wrong. Setting a
script smaller than its base is how mathematics has been typeset for a century,
and TYPE_FLOOR_PT is explicitly a comfort floor stricter than any journal's:
the 7.0pt those tick labels render at is Nature's stated maximum for figure
text, and the 6.6pt exponent on gallery-encoding is above Nature's, PNAS's and
Science's minimums alike. A body floor applied to script glyphs is a category
error.
So scripts get their own floor, and 5.0 is where two independent sources land.
The LaTeX2e kernel's fontmath.ltx maps every body size from 5pt to 25pt to a
script and a scriptscript size and never sets math type below 5pt at any of
them; Nature publishes 5pt as its minimum for any figure text. Both are recorded
in EXTERNAL_CLAIMS.
What that leaves the row catching is matplotlib's divergence and nothing else.
LaTeX has three math sizes, and \scriptscriptstyle serves every level below
the first, so nesting deeper than two stops shrinking; matplotlib multiplies by
0.7 for six levels with no floor. At an 11pt base LaTeX would set that k at
6pt and matplotlib sets it at 3.77. usetex figures are exempt on the same
argument rather than for convenience: real LaTeX clamps, so there is nothing
there to catch.
With the sourced floor the corpus is clean, and it is not clean for want of exposure. Twenty figures, no verdict changes and no detail-string changes, with 22 script-carrying strings across four figures actually measured; the smallest is 6.65pt against a 5.0 floor.
The release procedure runs as written, and the version moves in five files rather than four. Both halves are defects that only ever ran on a release commit, so nothing exercised them until 0.8.0 was being cut.
Every [[tool.bumpversion.files]] entry applied to every bump, so the
changelog's ^## Unreleased$ was required by the bump that opens the next
development cycle as well as by the one that cuts a release. That bump runs
immediately after a release, when the heading has just been renamed to the
version and the next notes do not exist, so it failed every time it was run.
0.7.0 is what that cost: its cycle never opened, the tree kept reading 0.7.0,
and 0.8.0 could not be cut with the documented command.
uv.lock records the project's own version and nothing wrote it, so it still
read 0.7.0 after 0.8.0 shipped. That one was not cosmetic. Any command that
syncs the environment rewrites that line to match pyproject.toml, and a bump
refuses to start on an unclean tree, so the version site nobody maintained was
blocking the command that maintains the rest. It needs anchoring rather than a
plain search: the lock names a version for every package in the graph, it is
sorted by name, and it currently carries annotated-types 0.8.0, ast-serialize
0.6.0 and mdurl 0.1.2, all versions this project has shipped. An unanchored
search cutting 0.8.0 would have found annotated-types first and pinned a
dependency to a version that does not exist.
A string is iterable, so a venue passed positionally was accepted. It
landed in the context_axes slot, was iterated into a frozenset of axes ids
rather than raising, and the figure was measured at the wrong page width: a
wrong verdict, reported green, from an argument order. Keyword-only is the only
shape in which that call cannot be written.
The gate that requires this to be written down could not be satisfied.
audit_api.py matched a name griffe reported with \b on both sides, and half
the names it reports cannot clear that: a parameter change comes back as
audit(context_axes), and a \b after the ) asks for a word character next
to it, which no sentence puts there. So the keyword-only change above failed CI
with the section naming every one of the five parameters. Eight releases passed
because griffe had only ever reported bare names like GATES and delta_e,
which end in a word character. Lookarounds instead, which keep what \b was
there for: delta_e still does not match inside delta_error.
Most of the fixes above are one round of false positives, found by putting two constructs into the corpus that were not in it. An annotation drawn with a leader line and a secondary axis between them exposed six rows that failed correct figures, and the pattern in all six is the same: a gate read an artist's window extent, or an rcParam, or a quantised colour, and took it for a fact about the figure when it was a fact about how the measurement was taken.
An annotation's window extent spans its text and its arrow together, so a
one-character label measured 285 points wide and ordinary annotated figures
failed all three text rows. Drawing a leader line is the remedy
Label attribution's own [FIX] and docs/gates.md both offer, and taking it
could not discharge the row: a leader exists to set the string away from the
ink, so the string was measured nearer whichever curve lay in between. Two
quantities in different units whose ticks happened to coincide were told to use
sharey. Contrast stack called float() on an array, raised, and the raising
gate became a hard failure. winter and Wistia failed on quantisation
artifacts of about 0.001 OKLab, amplified by their narrow lightness spans.
The construct ten rows were taught to look inside, the corpus had no example
of. ax.inset_axes was fixed for in this cycle and swept for with nothing to
sweep: every inset in the twenty figures was empty, so a change that taught ten
gates to walk child axes moved no verdict and could not have. gallery-broadening
is the material that sweep needed, and it carries the two other thin
measurements at the same time - colours sampled off a ramp by the author, which
check_colormap_kind's new reader had two panels of twenty to run against, and
two panels stacked on one x, which check_redundancy's new direction had one.
Writing it found four defects, none of them in a gate. _structural_values in
tests/test_alt_text_numbers.py walked fig.axes, so the two numbers the alt
text gives for the window the inset magnifies resolved against nothing: the
harness that reads the corpus had the same blind spot the gates were fixed for.
The figure's own alt text claimed the doublet merges by 400 K when the drawn
curves merge by 300, and claimed a residual negative at the line centres when
the builder held each line's peak rather than its area, so broadening only ever
added absorbance and the lower panel was positive at all 2400 samples. And the
inset's tick labels are the only text this sheet puts inside a panel, where
#777570 measures 3.5:1 on the host's own gridlines against the 4.60:1 it has
on bare page outside the frame; they are cased, which is the remedy the
readability row names for a gridline. A bbox was tried first and passed
nothing, correctly - the backdrop is sampled with the text hidden, which takes
the box with it.
One thing here is not a defect. gallery-orbit.png is rebuilt with no pixel
changed: its embedded Description still carried an em dash from before that
sentence was rewritten, so the committed PNG's alt text and the source's had
been two different strings.
Overplotting could not see half the ways a cloud is drawn, and the corpus
figure that says so in a comment was one of them. ax.plot(x, y, "o") and
ax.scatter(x, y) put the same marks in the same places; the row walked
ax.collections, a marker-only Line2D has no offsets, and the answer for the
plot spelling was "no scatter overplotting" every time. gallery-orbit
carries a comment saying the gate warns on it and that the warning is one to
read and accept. It did not warn. The comment had been untrue since it was
written.
The reason this took three attempts is that the obvious fix is wrong in a way
the corpus reports as a false positive. Taking markersize for the drawn
diameter moved three figures, gallery-orbit to a flat 100%, and a corpus
rejection at 3 of 20 looks exactly like the overplotting negative result
already pinned in this file. It was not one. markersize is a diameter for
most markers and not for all of them: lines.py special-cases "," and skips
the scale entirely, so that marker is one device pixel however large the number
is, and at ms=5 and 150 dpi the naive reading gave gallery-orbit's marks a
radius seventeen times their own. "." carries its own scale(0.5). "|" and
"_" have no extent at all across the stroke, so nineteen censoring ticks on
gallery-survival were being read as nineteen five-point discs and reported at
63% and 83%. Measuring the marker's own path instead, gallery-survival drops
out of the result, gallery-orbit reads 95%, and what remains is two figures
rather than three.
Both of those two were then checked against the render before the row was
allowed to fire, by counting the connected components of each artist's ink
alone: gallery-forms draws 14 marks as 7 blobs and 12 as 8, so half of the
first strip is not separately countable, and gallery-orbit is a bifurcation
diagram whose chaotic band is the finding. Neither is a false positive. This is
not a threshold argument and there was nothing here to pin.
Corpus exposure, since a clean sweep proves nothing without it: 7 marker-only
artists on 3 of 20 figures, of which 2 figures moved. The scatter half of the
same row is exposed at 3 artists on 2 figures. Both sides measure the marker's
path and not the edge stroked around it, which under-reports the drawn mark by
markeredgewidth on both, consistently. Counting it is more truthful and is
left to its own commit below, where the stated cost turned out not to be real.
The edge stroked around a mark is ink, and the reason for leaving it out was
a property of two rcParams rather than of the two APIs. The argument for
under-reporting together was that scatter_diameter_pt omits the stroke, so
counting it on the plot side alone would make one row read the two spellings
of one figure differently. Measured at 600 dpi, that symmetry holds only where
matplotlib already draws symmetric marks. Under bare defaults
lines.markeredgewidth and patch.linewidth are both 1.0 and one 4pt mark
renders 5.16pt either way; under this project's own figure.mplstyle they are
0.0 and 0.7, and the same mark renders 4.20pt from plot against 4.92pt from
scatter. Omitting the stroke bought agreement in the case that already agreed
and manufactured it in the case that does not.
Where the stroke lands is measured too, because marker strokes are butt-capped and a segment does not grow past its own ends. Ink minus path, at 600 dpi:
"o" mew 1 +1.12 across +1.12 down "|" mew 1 +1.20 across +0.04 down
"o" mew 2 +2.08 across +2.08 down "|" mew 2 +2.04 across +0.16 down
One rule covers both, and it subsumes the older bar-marker special case rather than sitting beside it: the stroke widens an axis exactly when the path has extent in the other one.
The stated cost of this change was gallery-parity moving from 49% to 55% and
flipping. That number was wrong. Parity is spelled edgecolors="none", which
leaves get_edgecolors() an empty array while get_linewidths() goes on
reporting the 0.70pt patch.linewidth default, so the 55% was a stroke the
render does not contain. The naive version of this change would have shipped a
hard false positive on the one corpus figure the question reaches. Asking
whether an edge is drawn before asking how wide it is, the corpus holds 10
mark-cloud artists across all 21 figures, 2 of them with a stroke actually
drawn, both of those gallery-survival's "|" and "_" where the stroke was
already the whole measured width. 0 verdict changes. The exposure is
honestly near zero and the figure that would have moved is the one that proves
the naive reading wrong.
Form failed a Gantt chart and a waterfall for a baseline neither of them
has, and only when they were drawn the documented way. _baselined_bars
excluded both from the day it landed: a Gantt shares no edge at all, and a
waterfall's segments neither share one nor rest on each other. But that
function is the fallback for bars built by hand out of rectangles, and
check_form consulted it only when there was no BarContainer to read. A
container says these are bars; it does not say they stand on a baseline. So
ax.barh(y, width, left=...) and ax.bar(x, height, bottom=...) went straight
to the truncation verdict, and one figure passed drawn by hand and failed drawn
with the helper matplotlib documents for it.
The row's own advice is the tell. "Bar length encodes the value, so a cut baseline misstates every ratio" is true of a bar chart, where every length is measured from one edge. A Gantt bar's length is a duration and its position is a start date; a waterfall segment's length is a delta and its base is the running total. Neither is measured from the axis edge, so there is no ratio to misstate and "use a dot plot" is not a fix for either.
Constructed rather than swept, because the corpus cannot decide this: 2 of 21
figures carry bars, gallery-counts and gallery-rose, both on a shared
baseline and neither moved. Six forms, drawn both ways:
bar chart, truncated fail gantt, ax.barh(left=) pass
bar chart, full pass waterfall, ax.bar(bottom=) pass
stacked, truncated fail stacked, full pass
Before the change the two offset-baseline forms failed. After it all six agree with their own reading, and the hand-drawn and container spellings of one Gantt return the same verdict.
bars_rest_on_a_shared_edge is deliberately narrower than _baselined_bars
rather than the same test with an orientation passed in. Detection carries two
guards that are right for deciding whether a heap of rectangles is a bar chart
at all and wrong for deciding whether bars stand on a baseline: at least
FORM_BAR_MIN_PATCHES of them on the edge, and more than one distinct length.
Reusing them would have opened a hole at exactly two points, measured: a single
truncated bar and a row of three equal truncated bars both go from failing to
passing, and both still misstate their values. A stacked chart is the same trap
from the other side, since it uses bottom= too and its bottom row does rest
on a real baseline, so "carries an offset" was never the discriminator.
Mark ratio was right to fire on a size-encoded scatter, and the fix it
printed destroyed the encoding. The standing complaint was that the row
contradicts its own docstring, which ended "this gate is about marks whose size
is not carrying the value". Nothing else in the project ever behaved as though
that were an exemption: the how-to's worked example is a size ratio, the remedy
clips a size array, and a test pins the row firing on a size-encoded scatter
inside an inset. That one sentence was the only thing saying otherwise and it
is gone.
The bar exemption is about the channel, not about intent. Cleveland and McGill
put position and length near the top of the perceptual ranking and area near
the bottom, which references/choosing-a-form.md already states and cites. A
bar thirty times another bar is read as thirty. A mark thirty times another
mark is not read as thirty by anybody, whoever meant what by it, so a bubble
chart is the last figure that should be exempt: it is precisely the case where
the reader is asked to decode a number off the weak channel.
What the argument was really pointing at is one line below the verdict. The row
printed [FIX] cap at 5.0x unconditionally, and suggest_fixes offered a
snippet that clips the size array. Run against a 60-mark bubble chart, that
snippet collapses 52 of the 60 onto one size, draws every value from 5.8 to
39.9 identically, and turns the row green. It fixes the audit by destroying the
data.
That shipped because of a real gap in the round-trip harness, which is worth
naming: tests/test_suggest_fixes.py executes every snippet against a figure
that fails its gate and requires the gate to pass afterwards. Clipping passes
that test for both cases. The harness cannot see that the figure no longer says
what it said, and its Mark ratio fixture is an ornament, so the destructive
case was never built. test_clipping_a_size_encoding_really_does_destroy_it
now pins the cost directly.
The advice is now branched on MARK_ORNAMENT_GAP, the ratio of the largest
mark to the next largest, which is the stated harm ("one mark far larger than
the rest") measured directly rather than inferred from the full range:
ornamental star 33.3 bubble chart, continuous 1.02
two `plot` markers 100.0 bubble chart, 3 categories 1.00
gallery-density 1.06
Above the gap, capping the range is right and the row says so. Below it the
sizes are graded, and the row says the fix is the form rather than the numbers,
which is the same answer Form gives about a truncated axis. The verdict is
unchanged in both cases. Corpus exposure: 1 of 21 panels carries more than one
scatter size, gallery-density at 110 distinct sizes and 3.8x, which passes
and did not move.
Contrast stack over-fired on both of the forms where alpha is doing real
work. Two complaints, and both were the row asking a question the figure was
not answering.
A fan chart was allowed two bands. The per-point branch has always held that
a continuous alpha encoding on one artist counts once, "because a continuous
encoding is a single decision". A fan chart is that same encoding spelled
across separate artists, and it was counted once per band. Worse, the opaque
median line the row itself demands for a focal point took one of the three
slots, so with ALPHA_LEVELS_MAX at 3 a three-band fan already failed, and
the printed advice was to draw fewer prediction intervals. Non-opaque alphas on
overlapping fills of one colour now collapse to one level once there are
ALPHA_RAMP_MIN_STEPS of them.
The collapse is scoped to fills, and that scope is the whole of it. Overlapping
fills in one colour are one interval encoding; lines in one colour are
separate series told apart by opacity, which is precisely the haze this row
exists to catch, and
test_contrast_stack_counts_alpha_levels_inside_an_inset had six of them
pinned. An earlier draft grouped by colour alone and turned that pin green.
A single flat alpha is not a stack. "Nothing is opaque, so the figure has no
focal point" presupposes something to focus on among alternatives. A density
scatter drawn wholly at alpha=0.3 asserts no hierarchy and has no ranking to
leave headless, and the remedy the row printed - raise the artist that carries
the point to alpha 1 - destroys the encoding it is aimed at, the same shape of
defect as the Mark ratio clip above. The opacity test now applies only where
more than one level is present. A per-point ramp also lands at one level and is
not exempt, because there the ramp is the hierarchy; two levels with nothing
opaque still fail.
That leaves "is this figure too pale to read", which belongs to Ink coverage
and is measured off pixels rather than guessed from alpha. Measured: a
3000-point scatter at alpha=0.01 still lays 12% ink across its panel and
reads perfectly well as a density field, while three lines at alpha=0.02
reach 1% and that row warns. Alpha alone cannot tell those apart.
A contrast floor was built here first and then thrown away, which is the part
worth keeping. Compositing each artist over its panel and requiring WCAG 2.1's
3:1 non-text ratio sounds principled and condemns the project's own palette:
Okabe-Ito orange #E69F00 measures 2.25:1 on white at full opacity and can
never clear that floor at any alpha, while the green needs 0.9 and the blue
0.7. It is also a floor this project deliberately keeps advisory in
check_palette, where a sub-3:1 hue is legal and merely obligates a second
channel. Borrowing it as a hard gate would have been the same category error as
judging a mathtext script against the body type floor.
test_the_contrast_floor_this_row_does_not_use_would_condemn_okabe_ito pins
the measurement so the idea does not come back unexamined.
Corpus exposure: 3 of 21 figures carry more than one alpha level or any filled
region at all, gallery-density, gallery-orbit and gallery-uncertainty.
None has three bands, so the corpus is not exposed to the collapse and its
clean sweep says nothing about it; the evidence is an eleven-case constructed
matrix instead. 0 verdict changes.
Series color on a single-hue ordinal ramp: no change, and the measurement
that decided it. The standing complaint was that this row rejects every
4-step single-hue ramp, leaving ordered stacks unconditionally red. The
premise does not survive construction. On an ordered stacked bar chart,
#0c0c0c #595959 #a5a5a5 #f2f2f2 passes both separation rows, and so does a
3-step blue:
What fails is a scheme whose steps are too close. ColorBrewer Blues 4 fails
because #eff3ff and #bdd7e7 are dE 9.5 apart under protanopia, and
check_palette's ordinal rows fail the same end independently for contrast
against the surface: #eff3ff at 1.11:1. Two different questions, one answer,
which is that the light end of that scheme does not hold up on a white page.
The row's own advice, re-step the ramp, is the right one and is achievable.
There is a real ceiling underneath and it is now stated rather than left to be rediscovered: one hue has a finite lightness range and the adjacent floors want about 21 dE, so a single-hue ordinal encoding runs out of room at five steps even in grey, the most separable hue there is.
The exemption was built and thrown away, which is the part worth keeping.
Detecting "these hues are a ramp" and swapping the categorical rows for the
ordinal ones is the obvious fix, and at these lengths a colour-only detector is
a coin flip. cmap_kind refuses to classify fewer than CMAP_QUALITATIVE_N
samples; reaching past that guard to the underlying monotone-lightness test
calls random draws from an Okabe-Ito/tab10/Set2/Dark2 pool a ramp about 2/k!
of the time, which is simply the chance that k arbitrary colours come out
sorted:
k=3 categorical pool 34.8% uniform sRGB 34.0% (2/3! = 33%)
k=4 categorical pool 9.7% uniform sRGB 9.2% (2/4! = 8%)
k=5 categorical pool 2.8% uniform sRGB 1.9%
k=6 categorical pool 0.4% uniform sRGB 0.2%
At four steps that is roughly one panel in ten silently losing its CVD separation gate, which is the only reason this row exists. The 40-sample guard is a decision, not an oversight, and four tests now pin both halves so neither has to be rediscovered.
The grain of truth in the complaint is real and is written down: the escape
hatch _data_colors_by_axes documents, drawing an ordinal ramp as
c=values, cmap=... so it is read as the value it is, is genuinely unavailable
to a stacked bar chart, which has no colormap route. The answer there is to
step the ramp wider, not to guess at intent from four hexes.
Text readability counted a gridline through an annotated heatmap cell as
data ink, and the pixels it counted were not the gridline's. The clutter
clause flags a pixel that differs from a local average and then forgives it if
its colour is furniture. TEXT_EDGE_WINDOW is 9, so within four pixels of a
white rule the local average is pulled toward white, and the flat cell either
side differs from it by more than TEXT_EDGE_TOL while still carrying the
cell's own colour. An exemption that only knows about furniture can never
forgive those. Instrumented on a 5x5 viridis heatmap with white major
gridlines through the cell centres:
450 of 646 pixels flagged as edges
106 actually the rule's colour, forgiven
344 the cell at (31, 146, 140), counted as data ink -> 53% of the box
The ground the label sits on is now an anchor beside the furniture, which
closes it exactly. _near_any measures distance to the segment between a pair
of anchors, so the rule is explained by the furniture, the cell by the ground,
and the antialiased shoulder where they meet by the segment joining them. The
ground is the median of the non-edge pixels, which is the surface by
construction.
The obvious alternative would have blinded the row: dilating the furniture match by the blur window sounds equivalent and is not, because the page colour is furniture and every pixel on a white figure sits next to page. Measured before and after on four fixtures, only the artefact moves:
curve through a label 15% -> 15% scatter cloud behind a label 20% -> 20%
thin curve through a label 8% -> 8% heatmap, gridline and a curve 76% -> 28%
The last one moves to what the curve alone accounts for, and still fires. A figure that measured 0% clean gained a gridline and went to 42% before this and stays at 0% after, which is the pair the new tests hold.
One thing the complaint blamed on the clutter clause belongs to the contrast clause and is correct: on a heatmap with white gridlines and white labels, the row fails for contrast, because white text lying on a white rule is 1.0:1 wherever the two meet. That is a real defect in the figure and the test fixtures use a grey grid to keep the two clauses apart. Corpus sweep: 21 figures, 0 verdict changes.
Auditing one figure twice returned two verdicts, and it is the same
measurement error one level up. examples/demo.py builds and reports inside
plt.style.context and hands the figure back with the context closed, so a
caller who audited the returned object was measuring somewhere else. demo and
encoding printed all-PASS from inside their own builders and failed the sweep
that audited them a moment later.
The mechanism is not a family fallback. font.family is captured into each
Text artist's FontProperties at construction and does not move; the list that
serif resolves through is not captured. The sheet leads font.serif with STIX
Two Text and matplotlib's default leads it with DejaVu Serif, so the same label
at the same nominal size measured 100.0 px instead of 82.0.
constrained_layout re-solved against the wider tick labels and moved the axes
9 px, the annotations are anchored in data coordinates and did not follow, and
Label attribution read a label as nearest a curve that is not its own.
Pinning the rcParams a measurement depends on is the same move MEASURE_DPI
already makes for resolution, and it is the second half of one bug class: a
measurement read against a knob nobody pinned. The record is taken at the first
audit because there is no hook at construction, so a figure whose first audit
happens outside its sheet records the wrong baseline and is then wrong
consistently rather than differently each time.
A fallback nobody runs is a gate nobody has. _contact_fraction takes a
tree when scipy is present and enumerated every pair when it was not. The
enumeration was written as the obviously-correct branch, and it is correct:
it is also quadratic in memory, and the pytest legs of CI install matplotlib
and nothing else on purpose, so it is the branch CI actually runs. On
gallery.orbit's 168000 marks it asks for a 168000 x 168000 float64 matrix,
226GB, on every audit of that figure.
Only the macOS leg went red, which is what made this look like a memory
ceiling rather than a bug. It is a difference in what the two kernels do with
an impossible mapping: Linux refuses it and macOS accepts it and then kills
the process, so the leg came back on SIGKILL, returncode -9, with two xdist
workers down beside it and the buffered stdout that would have named the
figure lost with them. The -n 2 cap on that leg, and the note above it
blaming the arm64 image's memory, were both written against this symptom. The
cap is left in place and the note now says what was actually wrong.
The replacement is a uniform grid of cell width r_maxA + r_maxB over the
same octave grouping, so a mark is compared against the 3x3 block around its
own cell and against nothing else, and the width is a pair of groups' bound
rather than the scatter's for the reason the grouping exists: one oversized
mark widens only the blocks it is an end of. Measured on the leg that was
failing: the four tests it killed now pass in 19.3s with no scipy, against
21.1s for the same tests with scipy installed.
Held to brute force rather than to the other implementation. The dense
enumeration moved into tests/test_figure.py as a fixture, and both real
paths are asserted against it across graded radii, one oversized mark,
zero-radius marks and sub-pixel marks. Corpus exposure, which the scipy sweep
does not provide because it never reaches this branch: the 21-figure sweep run
with scipy uninstalled is byte-identical to the sweep with it, and before this
it could not be run at all.
A gate that invents its own geometry pays for it twice. _series_px sent
every Line2D to _polyline_px and so to _densify_px, including one that
draws no stroke. plot(..., linestyle="none", marker=",") is the ordinary
spelling of a dense cloud, and gallery.orbit draws 168,000 points that way in
scattered order: densifying to a 2px gap returned 10,308,917 points, 157 MB,
61x the input. An audit() of that figure peaked at 426 MB, 368 MB of it
held by a polyline nobody drew.
The correctness half came first. The gate was measuring a label against chords
joining marks the figure never connected, which is exactly what _densify_px's
docstring warns about and what _marks_px was written to avoid one gate over,
in _rides_on. Both now use the same discriminator, _artist_kind, which
already returned marks for this artist. Marks are read from the raw vertices
rather than through _drawstyle_xy, because matplotlib draws them there:
"Markers must be drawn ignoring the drawstyle", Line2D.draw.
The memory was the second half, and it is what turned a wrong verdict into a
red CI leg. The macOS runner has half the memory of the Linux one, and the two
orbit legs of tests/test_renderer_invariance.py build and audit that figure
at five authored dpi each. Measured on the two tests that crashed their xdist
workers: 991 MB peak resident, down to 417 MB, and 14.4s down to 4.4s. The
two tests/test_example.py subprocesses that came back on SIGKILL measure 641
MB down to 350 MB. The -n 2 cap on the macOS leg was headroom rather than a
repair and is left in place; it is now headroom over a figure that no longer
needs it.
Corpus exposure, since a clean sweep proves nothing without it: 21 figures, 0
verdict changes, and 9 stroke-less Line2D artists across 22 builders, of
which eight carry 19 points or fewer. Only orbit is large enough for the
difference to be visible, and orbit matches no direct label, so the sweep was
exposed to the memory cost and to almost none of the correctness change. The
evidence for that half is the adversarial figure in
test_a_cloud_drawn_as_plot_markers_is_not_a_rival_along_its_chords, whose
marks sit in two far corners while its invented chords run straight under the
label on the curve that owns it.
Changed¶
audit(context_axes),audit(venue),report(context_axes),report(venue)andreport(suggest)changed to keyword-only. Avenuepassed positionally landed in thecontext_axesslot, where a string is iterable and so was accepted silently, and the figure was then measured at the wrong page width.audit_api.pymatches a reported name with lookarounds rather than\b. The parameter names griffe reports end in), which\bcannot follow, so the gate could not be satisfied for a parameter change by any wording. It is the first such change this project has made.
Added¶
check_palette.cmap_kind_rgbandcheck_palette.cmap_back_travel_rgbclassify a ramp from float sRGB. The hex-takingcmap_kindandcmap_back_travelare unchanged.- Two gallery figures,
gallery-calloutandgallery-secondary-scale, carrying the two constructs that exposed most of the fixes below: an annotation drawn with a leader line, and a secondary axis. The corpus is thirteen figures.
Fixed¶
Contrast stackno longer fails a figure that uses matplotlib's per-point alpha.float()raised on an array and the raising gate became a hard failure. An alpha ramp now counts as one level, because a continuous encoding is one decision the reader resolves.Text collision,Label attributionandText readabilitymeasure a callout's string rather than its leader line. An annotation's window extent spans text and arrow together, so a one-character label measured 285 points wide and ordinary annotated figures failed all three rows.Label attributionreads an annotation at the anchor its leader points to, rather than at the string. Drawing a leader line is the remedy the row's own[FIX]anddocs/gates.mdboth offer, and taking it could not discharge the row: a leader exists to set the string away from the ink, so the string was measured nearer whichever curve lay in between. A leader drawn to the wrong curve still fails.Label attributionno longer judges a panel title, axis label or colorbar label as a direct label.Axis redundancyrequires the panels to share limits, scale type and axis title before it calls a tick column repeated. Two quantities in different units whose ticks coincide were being told to usesharey.Clippingrecognises off-view ticks on a child axes, so asecondary_xaxisorsecondary_yaxisno longer reports them as clipped text.Colormap kindclassifies a ramp before the 8-bit round trip.winterandWistiafailed on quantisation artifacts of about 0.001 OKLab, amplified by their narrow lightness spans.
0.8.0 — 2026-08-18¶
What changed¶
delta_echanged what it returns: CAM02-UCS ΔE, not OKLab ×100. Same name, same signature, different number, and the sharpest edge in this release.oklab_distancewas added, returning exactly whatdelta_ereturned before.linear_to_cam02ucswas added: a stdlib CIECAM02, held to colorspacious within 1e-9 on identical XYZ.CVD_TARGETchanged 8.0 → 10.5;NORMAL_FLOORchanged 15.0 → 21.0;CMAP_WRAP_DE_MAXchanged 3.0 → 1.0.- All six cycle slots now clear all-pairs. Okabe-Ito's orange and yellow miss the new normal-vision floor at 20.75 against 21.0.
auditdraws atMEASURE_DPI = 150and hands the figure back on the dpi it arrived on.check_inkandcheck_text_readabilitydo the same when called directly. No verdict changed at 150 dpi; verdicts at other authored dpi changed to match it.DOCUMENT_TO_GATE_MAXchanged 0.92 → 0.93 → 0.998 → 1.009.getting-started.mdis gone, split acrosstutorial.md,install.mdandcompatibility.md. A link or bookmark to that page breaks.- Added:
tutorial.md,install.md,cli.md,compatibility.md,docs/how-to.md, and API-page entries for the 21 gate functions. - Added:
tests/test_renderer_invariance.py,tests/test_external_style_corpus.py,tests/test_suite_balance.py,tests/test_tutorial.py,tests/test_how_to.py. - The declared
matplotlib>=3.8floor is asserted against CI's matrix. - Seven unused markdown extensions removed from the site config;
navigation.tabs,sections,pathandfooterset; nine pages carry their own meta description. - Corrected:
design.md's "0.988 specificity" credit, the Science type floor (retracted, it publishes none), PNAS's 6pt (one requirement in two units, not two floors), a blank panel's furniture reading, and the mermaid diamond ongates.md.
Why it changed¶
The separation gates measure in CAM02-UCS instead of OKLab, and both floors moved. This is the largest correctness change the project has made and it changes verdicts, so it is first.
delta_e returned OKLab Euclidean distance ×100 and the two separation floors
were quoted in it. OKLab was fitted for hue uniformity and never calibrated
against discrimination data, so a distance of 8 in it had no referent: there was
no measurement anyone could look up saying what a reader does at 8, which meant
CVD_TARGET = 8.0 was a preference wearing a citation's clothes. Worse, the CVD
rows measured that uncalibrated distance between colour-blind simulations —
coordinates OKLab was never fitted for at all.
Measured against colorspacious (CAM02-UCS + Machado) over 79 800 pairs the validator would accept as series slots, the old metric ranked pairs correctly (Spearman 0.964, ROC AUC 0.988) but its operating point did not: specificity at the shipped floor was 0.786, so about one pair in twenty that the gate passed an independent implementation called too close, concentrated in violet (12.8%) and blue-violet (11.7%). The same measurement now reads 0.988.
delta_echanged what it returns: CAM02-UCS ΔE, not OKLab ×100. Same name, same signature, different number. A caller comparing its result against a hard-coded threshold gets a wrong answer silently, which is the sharpest edge in this release.oklab_distancewas added, returning exactly whatdelta_ereturned before, for callers who need the old scale.linear_to_cam02ucswas added: a stdlib CIECAM02, held to colorspacious within 1e-9 on identical XYZ bytests/test_colour_space_oracle.py.CVD_TARGETchanged 8.0 → 10.5 andNORMAL_FLOORchanged 15.0 → 21.0. Both were re-derived from Stone, Szafir & Setlur (2014), not rescaled: the per-pair ratio between the two spaces runs 1.16 to 2.02, so no single factor converts them.CMAP_WRAP_DE_MAXchanged 3.0 → 1.0, which is now one JND rather than a number picked between two clusters.
Two consequences worth knowing before you upgrade:
All six cycle slots now clear all-pairs. The guide said five, because the
sixth pair measured 7.9 against a floor of 8. In CAM02-UCS the worst all-pairs
view is a different pair — #0072B2 vs #CC79A7, at 12.8 against 10.5 — and
it clears. Scatter and small multiples may use the whole cycle. This is the only
place 0.8.0 gives more room rather than less.
Okabe-Ito's orange and yellow miss the new normal-vision floor, at 20.75
against 21.0, the one miss out of that set's 28 pairs. The floor was derived
without reference to any palette, and yellow is one of the two colours
figure.mplstyle already drops from its cycle. Arriving at that independently is
the strongest evidence these floors have, so the result is pinned in a test
rather than smoothed away.
The composition gates measure at a fixed resolution, MEASURE_DPI = 150.
Half of check_figure's thresholds are pixel counts, and a pixel count is a
measurement only when the resolution is pinned. It was not: the gates drew at
fig.dpi, which is whatever the author set, whatever sheet is in effect, or the
authored value times the device pixel ratio of an attached display. Audited
across 100/150/200/300/600 dpi, the eleven gallery figures moved 34 rows and
flipped one. orbit's ink fraction ran 0.13 at 100 dpi down to 0.04 at 300
and out of the band at 600, because a mark's antialiased fringe is a fixed
number of pixels wide and so a shrinking share of a mark that grows with the
resolution. The figure never changed; only the knob did.
auditnow draws atMEASURE_DPIand hands the figure back on the dpi it arrived on.check_inkandcheck_text_readabilitydo the same when they are called directly, so a gate called on its own reports whatauditreports.- 150 is the number every pixel threshold was already calibrated at, so no threshold moved and no verdict changed at 150 dpi. Verdicts at other authored dpi changed to match it.
tests/test_renderer_invariance.pysweeps that range and requires every row identical down to the message, and puts the old behaviour back to check the sweep can still see it.- One documented number was wrong as a result and is corrected: a blank panel's
furniture does not always measure inside the ink band. Furniture is a
perimeter and a panel is an area, so at
MEASURE_DPIthe blank half of a 3x1.5in pair reads 0.03, inside it, and the blank half of a 6x3in pair reads 0.01, under it. Only the first is caught by asking whether anything was drawn, which is the mechanism the guide describes.
The composition gates are now measured against material this project did not
author. tests/test_external_style_corpus.py builds three neutral figures
under each of matplotlib's 28 shipped style sheets (seaborn's, Tableau's,
Petroff's, ggplot's, FiveThirtyEight's, Solarized's), holding the content fixed
so styling is the only variable. Four of those styles carry a ground-truth label
from their own authors, being published as accessible under colour vision
deficiency, and none of the four is rejected by the colour gate while 21 of
the 24 unlabelled styles are. Solarize_Light2 is the corpus's one WCAG text
failure, and the two presentation styles are its two clipping failures.
The negative result from the same sweep is pinned beside it: Style sheet and
Fonts fire on 28 styles out of 28. Neither is measuring the figure. The
first asks whether this project's sheet is in effect and the second asks for
Type 42 embedding that no stock style sets, and neither should ever be counted
as evidence that these gates discriminate.
The suite's balance is a number now, with a ceiling on it.
tests/test_suite_balance.py classifies every test module as measuring the
tool, checking a document against the code, or release plumbing, and gates the
document-to-gate ratio. It arrived at a ceiling of 0.92 reading 0.910;
before the two sweeps above it read 0.977, which is the shape of the criticism
that prompted this: the documentation tests had very nearly caught the tool.
Raising the ceiling means writing the measurement the prose is standing in for,
or arguing a module is classified wrong. The documentation work below moved it
four times under that rule and ended by inverting it; the final reading is
recorded there.
The declared matplotlib floor is checked against CI's matrix.
matplotlib>=3.8 was a support claim that nothing verified was ever run. It is
true (ci.yml pins a 3.8.4 leg), and it is now asserted, so raising the floor
without moving the leg fails rather than quietly shipping a claim no test has
touched.
Documentation, unchanged from what was already here:
The documentation is restructured by Diátaxis, one mode per page. The split
before this was by audience, author against maintainer, which left four modes on
one page: getting-started.md was an install how-to, a tutorial, a requirements
reference and an explanation of the API contract at once. gates.md had the CVD
sweep rationale welded into its reference table, and how-to.md carried a
21-row reference table. The site now splits by what the reader came to do:
- Tutorial:
tutorial.md, new. One path, no alternatives, every transcript captured from running the steps in a clean directory. - How-to:
install.md, new, andhow-to.md, task-titled. - Reference:
gates.md,cli.mdandcompatibility.md, the last two new, andapi.md. - Explanation:
design.md,style-guide.md,choosing-a-form.md,gallery.md.
getting-started.md is gone, split across tutorial.md, install.md and
compatibility.md, so a link or bookmark to that page breaks. Sentence-level
voice follows Google's technical writing course: second person, active voice,
one idea per sentence, key point first. The project history stays, quarantined
in the explanation pages where Diátaxis puts it.
Two claims were wrong and are corrected rather than carried over:
design.mdcredited the colour oracle with "0.988 specificity". 0.988 was the ROC AUC of the superseded OKLab metric; that metric's specificity was 0.786, andtests/test_colour_space_oracle.pypins the current one above 0.95.- The journal type floors, re-verified against the three publishers on
2026-08-17. Science publishes no text floor at all, so the "5-7pt labels,
6-8pt axes" it was credited with is retracted. PNAS gives 6pt and 2mm as one
requirement in two units, not two floors, and also sets a maximum the docs
never carried. Nature's 5pt minimum and 7pt maximum are confirmed. The
retraction sweep found the same wrong sentence still in
check_figure.pyafter both documents were fixed, which is what that sweep exists for.
Adding pages pushed the document side of the suite past the gate side and over
the ceiling. It was paid the way tests/test_suite_balance.py asks, with the
measurement the new prose stands in for: tests/test_tutorial.py builds each
tutorial step's figure and asserts the row transitions, so the tutorial cannot
silently stop working. Ratio 0.985 against a ceiling of 0.998 that did not move.
Every site feature the config names is now asserted, and the ones that do
nothing are gone. Seven markdown extensions were configured that no page used.
Six were inert; pymdownx.emoji read the ::: of a prose mention of an
mkdocstrings directive as a shortcode and swallowed the rest of the line into a
code span. The config comment claiming "only what the pages actually use" is a
test now, failing on any extension nothing uses.
The nav had been Diátaxis since the restructure, but only the sidebar said so.
navigation.tabs, sections, path and footer put the four modes in the
chrome. A feature name is accepted silently, so each is asserted: the four that
emit markup in tests/test_docs_site.py, and content.tooltips in
tests/test_docs_render.py, which hovers an abbr and reads the painted tooltip.
navigation.indexes and search.suggest measured as no-ops and are not set,
with the reason written beside the list; search.suggest is a Material feature
Zensical does not implement at all. Nine pages carry their own meta description,
where all nine had shared one.
DOCUMENT_TO_GATE_MAX changed 0.998 → 1.009, and the documentation side
is now the larger of the two: 1.0088 measured, 4919 document lines against 4876
gate lines. Both additions that moved it found a live defect, which is the
payment that file accepts.
The site is themed, and the home page's card grid renders on GitHub too.
zensical.toml swaps the default book-open glyph for a fence logo and
palette.css adds the accent underline tint for fg-blue and fg-sky. The
card grid used Material-specific syntax, a markdown-attributed div plus
:lucide-* shortcodes, which GFM does not parse: markdown inside an HTML block
is passed through raw and the shortcodes are unknown to it, so the whole block
rendered as literal text on GitHub. It is raw HTML with inline lucide SVGs now,
which is cards on the docs site and a clickable link list on GitHub.
The mermaid diamond on gates.md says what it meant to say. mermaid 11
renders a literal \n in a quoted diamond label instead of breaking the line,
so the need node used <br/>. tests/test_docs_render.py measures the
diagram's painted labels, so the defect cannot ship again.
Earlier in the same cycle, before the restructure:
The docs say which import line a given install wants. 0.7.0 moved the
installed modules into a package, and the two indexes do not publish in the
same hour: conda-forge follows PyPI through the feedstock's autotick bot, so
for a while after each release conda install hands back the release before
it. On the day 0.7.0 shipped that was 0.6.0, whose modules are flat and whose
import line is the vendored one. The README and compatibility.md name the
version each import line belongs to, and how to read which one you got, rather
than presenting the two install routes as interchangeable.
The vendoring instructions cover suggest_fixes.py. They copied three
files and named two scripts while the README advertised a third, so the route
the docs call the default was the one route with no way to reach suggest. It
is a fourth cp, marked optional, beside a sentence saying what a copy without
it loses and what check_figure.py genuinely cannot run without.
py.typed is documented where a caller would look for it. It shipped in
0.7.0 and the release notes were the only place saying so.
The gates page names the row a crashed gate produces. The audit stopped losing itself to one raising gate in 0.7.0, and the row it reports instead is a row about the checker rather than about the figure, which is a thing a reader of that page has to be able to recognise.
The release procedure in CONTRIBUTING.md is the one that was followed. It
still said bump minor cuts a release, which stopped being true when the tree
started carrying a development version: bump dev cuts, and bump minor opens
the next cycle. Both bumps tag, release.yml triggers on any v* tag, and its
version guard compares the tag against the project rather than judging the shape
of either, so the cycle-opening tag is one that would publish a development
version to PyPI if it were ever pushed. The section says that, and it says that
the tag goes on the merged commit, which is where v0.7.0 sits and is not where
the bump put it.
One copy of the API promise. It was in the README and on the
getting-started page verbatim, 1246 characters each, in a repository whose docs
site is built on symlinks so that no page is a second copy of another. The docs
site has the statement, now on compatibility.md; the README has the two
sentences a reader of the PyPI page needs and a link.
There is a how-to page, and it is the one the docs did not have. Every page
on the site explained: gates.md what a row measures, style-guide.md what was
measured to land on the threshold. Nothing said what to type. A reader whose
build had just gone red on Type size had a 666-line essay and a table of
constants to work from, while report(fig, suggest=True) had been printing the
remedy for that row since the marks were split, undocumented anywhere a reader
would look. docs/how-to.md is the recipes: printing the remedies, the row
table with a first move for each of the 21, gating a suite, gating a palette
from a toolchain that is not Python, placing at a fraction of the content
width, alt text, reading one row, moving a threshold.
tests/test_how_to.py runs it. The row table is re-derived from GATES and
REMEDIES rather than proofread, the quoted scales are recomputed, the quoted
CLI output is the CLI's. Writing it found two defects in its own prose before
the page shipped: a paragraph warning about a difference between not s and
s is False that does not exist, since "warn" is truthy, and a REPL block
quoting page_scale as 1.380138888888889 when the value is a numpy.float64
and prints as np.float64(...).
The API page documents the 21 gate functions. They were exempt as a class,
on the argument that audit runs them and gates.md carries their thresholds.
What that left was 21 public callables whose signatures appeared nowhere, so
calling one meant reading the source to find out that some take a renderer.
check_colormap had no docstring at all, which is why it could not have been
added without writing one. test_the_page_documents_every_gate_in_order keeps
a gate added later from joining a blind spot instead of a page.
What gating the how-to page cost, and what paid for it. The page arrived
with claims the doc suite could not read. A REPL block is Python interleaved
with output, so ast.parse called a correct example a syntax error;
python_statements splits a session with doctest and parses each source,
and every prompt has to come back as an example so a block cannot pass by
having nothing left in it. A sentence about a snippet names what the snippet
bound, so ok, s and the predicates over them now resolve against the names
the corpus' own examples assign, parsed rather than listed. float() resolves
as a builtin call, numpy.float64 against numpy, and adjacent against the
choices= its flag is declared with. status came out of the unresolved
ledger: it resolves now, for a reason.
The link check in the docs job was reading ../api/#the-gate-functions as a
path and asking the filesystem for a directory named after the anchor. It
splits the fragment off, resolves the page, and then checks the anchor exists
on it, which is a check the old version could not make at all: a link into a
section somebody renamed used to land on the page and scroll nowhere.
test_ink_coverage_does_not_call_a_sparse_panel_empty had built a panel
measuring 0.0198 on matplotlib 3.8 and 0.0216 on 3.11, either side of the 0.02
floor, so one supported matplotlib passed it and another warned. The figure now
states its own weights and asserts its margin. That is a test defect rather
than a gate defect, and finding it exposed a real gap: nothing anywhere
asserted that a row's number is the quantity its name claims. The ink
fraction is now measured against a rectangle of known coverage, the
furniture-only reading is pinned at two panel sizes, and the mark-ratio, type,
line-weight, overplotting and alpha rows are asserted on what they print.
DOCUMENT_TO_GATE_MAX changed 0.92 → 0.93, moved by less than the
measurement written to pay for it.
0.7.0 — 2026-08-03¶
What changed¶
- Installed, the checkers are a package.
import check_figureno longer resolves;from figure_gate import check_figuredoes. The console scriptscheck-paletteandcheck-figureare unchanged, and vendoring is untouched. py.typedships. The style sheet installs tofigure_gate/figure.mplstyle. An install that named the sheet by its old path has to say the new one.pip install -e .no longer works on a clone;[tool.uv] package = falserecords that.- New gate:
check_banking, advisory, withBANKING_SLOPE_MAX = 10.0andBANKING_MIN_POINTS = 8.GATESgained a row and every row afterLine weightmoved down one, soaudit()returns 21 rows and not 20. This breaks anything indexing that tuple rather than reading it by name. - The remediation marker
<-became two marks,[FIX]and[WHY]. SERIES_ENCLOSED_FRAC = 0.7added: a fill holding that share of another series' ink is that series' band, rather than a rival, and a band no longer has to be labelled to be recognised.MACHADOandsimulate_anomalousadded, withANOMALOUS_SEVERITIES. The separation row takes the worst over them alongside dichromacy and names the severity its verdict came from.scatter_diameter_ptadded.sis a squared diameter, not an area, soMark ratioandOverplottingboth report different numbers than before.- Four gallery figures added:
gallery-uncertainty,gallery-counts,gallery-residual,gallery-density. The corpus is eleven figures. examples/gallery.pyandexamples/demo.pyare importable. The driver, the argv read and the exit are under__main__; the builders return their figures and write nothing withOUT/outset to None.- A gate that raises reports its own row instead of losing the audit. An advisory that crashed warns; a hard gate that crashed fails.
- The tree carries a development version between releases (
0.7.0.dev0here).uv run bump-my-version bump devdrops the suffix. - Nine thresholds moved to module level. Values unchanged, so no verdict moves.
- Added:
tests/test_thresholds_are_constants.py,tests/test_alt_text_numbers.py, andRETRACTED_CLAIMS. - Corrected in alt text: the slope graph's
eleven of twelve rise, the demo'sreaches 0.05 by epoch 6, and the field's28-step ... from (-1.9, 2.2). - Measured and not shipped: a size-weighted separation gate. The finding ships as a test; the gate does not.
- CI runs the suite on macOS and Windows. The sdist config is an allowlist. The
wheel excludes
audit_api.py.
Why it changed¶
Installed, the checkers are a package: from figure_gate import
check_figure. This is a breaking change on the install path and the reason
the next release is 0.7.0. Through 0.6.0 the wheel put check_figure and
check_palette at the top level of site-packages -- two of the most generic
module names a distribution could claim, on a namespace shared with every other
installed package. import check_figure no longer resolves; from figure_gate
import check_figure does. The console scripts check-palette and
check-figure are unchanged. suggest_fixes is new in this release and has
only ever been importable from the package.
Vendoring is untouched. The files stay at skill/scripts/, still import
nothing of each other at module scope, and a copied check_figure.py still
does import check_palette beside it -- the two sites that reach for a sibling
now try the relative import first and fall back to the flat one, so one file
serves both layouts.
Two things follow from the move. py.typed ships, so the annotations added in
the previous release are visible to a caller's type checker for the first time;
until now PEP 561 required every one of them to be read as Any, because the
marker has nothing to attach to when the modules are loose files. And the style
sheet installs to figure_gate/figure.mplstyle, beside the module that reads
it, rather than as a bare figure.mplstyle at the root of site-packages --
another generic name in a directory every distribution shares. A package
directory is already namespaced, so the sheet needs nothing around it: the
first location _style_sheet probes is beside the module, which is the
installed package on one route and a vendored copy on the other. An install
that named the sheet by its old path has to say the new one; the gate finds it
either way.
pip install -e . no longer works on a clone, and [tool.uv] package = false
records that. hatchling refuses editable installs when a sources entry
rewrites a prefix rather than removing one, which is what mapping
skill/scripts onto figure_gate does. Nothing in the suite needs the
installed package -- conftest.py puts skill/scripts on sys.path -- and
keeping the skill's own directory layout was worth more than the editable
install.
A gate that raises no longer loses the audit. audit ran its twenty-one
gates in a list comprehension, so one exception anywhere propagated and the
caller got a traceback instead of the twenty rows already measured. Each gate
is now called inside a try, and a gate that raised reports as its own row,
with the exception in the detail and a note that the defect is in the checker
rather than in the figure. The verdict follows the gate's own severity: an
advisory that crashed warns, a hard gate that crashed fails, because a gate
that measured nothing has not cleared the figure. No gate is known to raise --
twenty adversarial figures, including 3D, polar, all-NaN, infinite and
zero-sized ones, found none -- but matplotlib>=3.8 has no upper bound and
these gates read deep internals.
The version between releases says so. It is 0.7.0.dev0 here, and the last
step before tagging is uv run bump-my-version bump dev, which drops the
suffix. The tree used to carry the version of the release that had already
happened, so uv build on a checkout ahead of v0.6.0 produced a
figure_gate-0.6.0 wheel that was not the 0.6.0 on PyPI. Releases build from a
tag on a clean checkout and were never affected.
Two things the bump config said and did not do. Its ## Unreleased search was
unanchored, so cutting a release rewrote every mention of that string in the
file and not only the heading: the 0.6.0 notes explain the gate that requires an
Unreleased section, and shipped saying a missing ## 0.6.0 — 2026-07-30
heading. Those two sentences are repaired here and the search is anchored to a
line of its own. And message = "chore: release {new_version}" sat under
[tool.bumpversion.parts.dev], a table where nothing reads it, so both releases
cut with this config carried the stock Bump version: X → Y the key exists to
replace. tests/test_version_sites.py holds both, and holds the changelog to
having no release heading buried inside a sentence.
The source distribution lists what it is instead of what it is not. The
sdist config was a blacklist of agent-scratch paths and it had a hole:
.superpowers/ is neither tracked nor gitignored, so a local make dist
shipped a dozen task briefs and review diffs, along with any other untracked
file lying in the tree. It is an allowlist now, and .superpowers/ is
gitignored. Releases were never affected, for the same reason as above.
tests/test_docs_site.py reads the repository, not the working tree. It
walked docs/ off the filesystem, and .gitignore carries
docs/superpowers/, so a maintainer with design notes on disk got five
failures naming files that are not part of the project while CI stayed green.
It asks git ls-files now, and falls back to walking the filesystem where
there is no git to ask, which is how the suite keeps running from an unpacked
sdist.
CI runs the suite on macOS and Windows. One leg each, on the newest
supported Python and matplotlib; Linux still carries the version matrix. Font
resolution is the most OS-dependent thing check_fonts touches and every run
until now was on one Linux image.
Every function in the three modules is annotated, and the API page renders
as a reference. The 19 documented callables carry Google-style
Args: and Returns: sections, so each entry on the page is a signature and
two tables rather than three paragraphs. check_figure.py and
suggest_fixes.py gained from __future__ import annotations;
check_palette.py gained it too, which is what keeps tuple[float, float,
float] from being evaluated on the 3.8 the file still claims. The 21 gates
and every private helper are annotated as well, so the whole of
skill/scripts type checks rather than the documented surface of it.
Annotating found one wrong claim. check_palette.check documented status as
True or False, and the contrast row has returned "warn" since it became
advisory. The docstring now says what the function does, and the return type
says it too.
Gate.func was annotated object, which is not callable, and audit calls
it. It is now Callable[..., tuple[bool | str, str]], and Gate.needs is
tuple[str, ...] rather than a bare tuple.
The API gate stopped existing twice. ci.yml carried an inline copy of
skill/scripts/audit_api.py, and the two had drifted: the copy accepted six
changelog verbs where the script accepts twelve, missed an Unreleased section
that was last in the file, and had no branch for griffe being absent. A release
note saying a symbol "gained" a row passed make audit-api and failed CI. The
job now runs the script, which is the copy with tests.
suggest_fixes joins the compared modules. It was in neither roster, so
suggest was advertised as public and covered by nothing. Comparing it against
a tag older than the file needed a new branch: a module with no history at the
tag is reported as new rather than as griffe failing to run.
The gate also reads the release's own heading, not only ## Unreleased. The
release commit renames that heading to the version it cuts, in the same commit
that drops the .dev suffix, so the gate ran against an empty section and
failed every release carrying a break -- on the commit that had just written
the break down. It matches the heading to pyproject.toml's version rather
than taking whichever section is topmost, so a paragraph in a shipped release
cannot stand in for a break made after it went out.
What the API promises is now written down, in the README and in the getting started guide: every non-underscore name in the three modules, breakable by a minor bump below 1.0, with the row shape rather than the row count being what callers can rely on.
The wheel does not ship release tooling. audit_api.py, added this cycle,
compares this project's public API against its last tag and has no caller
outside this repository: it reaches the checkout through the audit-api target
in the Makefile and through its own test. The wheel excludes it, so the only
thing an install puts on the import path is the three modules a caller uses.
The remediation marker became two marks, [FIX] and [WHY]. A gate's
detail appended <- and everything after it was read, by the guide and by
test_a_gates_message_either_names_a_fix_or_is_named_here, as what to do. Six
clauses named no action. check_line_weight cited SIAM on strokes under a
point, check_banking cited Cleveland on 45 degrees, check_colormap's
qualitative-on-image branch explained that an image puts every category beside
every other, the normal-vision floor said two hues are hard to tell apart, and
check_contrast_stack and check_series_color each had a branch doing the
same. All six are true and none is a fix, so the test counted six explanations
as six routes to a fix, and the count of gates that route the reader was wrong
by six.
[FIX] now introduces an action and only an action; [WHY] introduces the
reason the row fired. A detail may carry both, in that order, which is what
keeps check_colormap's existing cut at the fix mark taking the whole
clause when it quotes a palette row. The marks are words rather than glyphs
because the arrow never said which of the two it was introducing, and splitting
it against a tilde would have put the distinction on one character in a wall of
detail text; [FIX] and [WHY] read against the [PASS]/[FAIL] the report
already prints. The six converted clauses gained a real action each: a minimum
linewidth computed at the figure's own scale, the panel aspect, an explicit
color per series. test_a_reason_clause_never_stands_in_for_a_fix is the new
direction, and it fails a gate that explains without routing.
Four gallery figures, added for the rows that had never measured anything.
Every gate returns a detail string, and reading all 21 of them across the seven
figures showed five rows passing without having run the code that decides: no
figure drew a confidence band, a bar, a diverging colormap, a signed contour set
or a scatter, so _encloses, check_form's BarContainer branch, the
diverging arm of cmap_kind, check_contour_dash and check_overplotting had
each returned a clean row seven times over having seen nothing. A row that
passes by having seen nothing looks exactly like a row that passed.
gallery-uncertainty.png puts a direct label under a confidence band on a log
axis, and is the only figure in the corpus audited for a place rather than for
its canvas (venue="neurips", placed_frac=0.75). gallery-counts.png is bars
from a zero baseline with a secondary_yaxis relabel, which is the twin-scale
case check_dual_axis exists to permit. gallery-residual.png is a diverging
field with solid signed isolines. gallery-density.png is a scatter whose
mark area varies, so the overplotting row's radius-octave path runs rather than
its equal-radii shortcut, beside a hexbin of the same measurement at 40000
points. All eleven figures pass every gate.
A confidence band on a log axis is its curve's band again. _encloses
asked Path.contains_points(pts, transform=t), which freezes the transform and
hands it to the C containment test — and that test applies its AFFINE part only.
On a log axis the band's outline was therefore tested at coordinates it does not
occupy, every point of the curve read as outside, and _encloses returned False
without raising. The band went back to being a rival for the curve it covers, at
0px from any label on that curve, so every direct label under a band on a
log-scaled figure failed check_label_attribution. Only the non-affine case was
ever wrong, which is why the linear fixtures beside it stayed green;
Path.transformed applies the whole transform, and the regression test is
parametrised over both scales.
A band is now told from a rival by what it encloses, not by whether it was
labelled. check_label_attribution skipped a filled collection unless it
carried a legend-visible label. The intent was right, since a confidence band
lies on top of the curve it belongs to and counting it as a rival ties every
direct label with its own curve at zero. The discriminator was not: labelling a
band for the legend is the normal reason to label one, and plot(label=
"signal") under fill_between(label="95% CI"), with "signal" printed on the
curve, returned "0px from its own curve and 0px from another". The label also
decided visibility rather than only rivalry, so an unlabelled band could drop a
panel below the two-series minimum and the gate skipped that panel outright.
Fills are harvested like anything else now, and the band relation is tested
where rivals are chosen: a filled region holding at least
SERIES_ENCLOSED_FRAC = 0.7 of another series' ink is that series' band. The
threshold separates two measured shapes. Adjacent stackplot bands share a
dividing edge, so each holds part of the other's outline and they have to stay
rivals; the worst reading over 200 random stackplots, two to five bands each and
degenerate near-flat ones included, is 43.9%. A fill_between band over its
curve's whole range reads 100.0%. The residual is recorded rather than fixed: a
band covering part of its curve reads in proportion, 88.1% over nine tenths of
the range, and below the floor goes back to competing with the curve it belongs
to. The Label attribution row is unchanged on the seven gallery figures that
existed then and on demo.py.
Constants quoted in prose are pinned against the code, not just the ones in
the table. CONTRIBUTING.md has been telling contributors that a constant
written `NAME = value` is held to the code by the doc suite. That was true
of the gate table's threshold column and of nowhere else, and
SERIES_ENCLOSED_FRAC = 0.7 in the paragraph beneath that table passed the
whole suite with a deliberately wrong value. Seventeen prose constants across
the documentation files are now checked the same way the column is.
One oversized mark no longer sets the overplotting query radius for the whole
scatter. _contact_fraction enumerated candidate pairs at 2 * r_max. The
bound is correct, since r_i + r_j cannot exceed it, but a single large mark
inflates it for every other mark in the figure, and a highlighted point in a
large scatter is an ordinary thing to draw. Measured: 50000 uniform points at
r=3 with one r=40 among them produced 62 million candidate pairs in a 994MB
array, and 60000 points on a Gaussian cloud with one r=100 mark did not return
in 120 seconds. The gate is advisory, but it runs inside audit, so what it
takes down is the whole audit.
Marks are grouped by radius octave, so radii inside a group vary by under 2x and
a group is bounded by its own largest radius. The nearest member of a group is
tested exactly first, which settles almost every mark, and only a mark still
unhit whose nearest member lies inside r_i + max(r_B) needs a ball query. The
oversized mark becomes a group of one. Same answers, asserted exact against the
full pair enumeration over 24 random scatters spanning graded radii, a single
oversized mark, zero-radius marks and sub-pixel marks; the uniform-radii fast
path and the scipy-absent fallback are untouched. The three cases above now run
in 0.06s, 0.07s and 0.21s.
The examples are importable, so the corpus can be measured. gallery.py and
demo.py did their work at import: every figure built, all eight committed PNGs
overwritten, sys.argv[1] read as an output directory, the style sheet applied
to the importing process for good, and then sys.exit. That made the corpus,
which is the evidence every gate is checked against, the one thing hardest to
get at; test_alt_text_numbers.py worked around it by cutting each source at a
marker string and executing the prefix. The driver, the argv read and the exit
are under __main__ now, the sheet is scoped to the builders, and the builders
return their figures and write nothing with OUT/out set to None. All eight
figures render byte-identical to the previous code.
A size-weighted separation gate was built, measured, and not shipped. The
intuition is sound: a hue pair that reads as two on a filled band ought to read
as one on a hairline, and a small target really does need more colour difference
than a large one. Stone, Szafir & Setlur (2014) measured how much, fitting the
noticeable difference as C + K/s over target sizes from 0.333 to 6 degrees of
visual angle. A gate multiplying NORMAL_FLOOR by that ratio warned on
gallery-convergence and on demo.py - on the Okabe-Ito cycle at the 1.6pt
stroke this project recommends.
That is not a threshold to tune, it is a unit error. The floors here are OKLab
dE x100 and the model is CIELAB, and measured over 20000 random pairs one OKLab
unit is a median 2.94 CIELAB. So NORMAL_FLOOR = 15.0 is about 44 CIELAB and
CVD_TARGET = 8.0 about 24, against the 10.4 the size model asks for at the
smallest size it was fitted at. The pair the gate flagged, Okabe-Ito's green and
sky blue, are 59.5 CIELAB apart - 5.7 times the requirement. The floors already
exceed what the size model demands at every size the model can speak to, and
publication line widths sit two decades below its fitted range, where
extrapolating an inverse-size fit produces a number nothing supports.
So the finding ships and the gate does not. test_the_size_model_is_already_
inside_the_normal_vision_floor pins the arithmetic, a second test asserts no
size-weighting helper was left behind with no caller, and the style guide states
the rule as a rule: a hairline is where a palette gets tested, so give thin
strokes the widest-separated slots. CONTRIBUTING says to drop a gate that
false-positives on the corpus, and this one did, on the corpus's own palette.
Dichromacy is not the worst case, and the CVD gate was reading only
dichromacy. Most colour vision deficiency is anomalous trichromacy - a cone
whose peak sensitivity is shifted rather than one that is missing - and
simulating the endpoint alone would be sound if the endpoint were the hardest
view. It is not. Measured over 240000 pairs of hues check_palette.py would
accept as series slots, 0.87% clear CVD_TARGET under dichromacy and miss it at
some lower severity, and dichromacy overstates separation by as much as 10.5 dE.
#288ac6 and #fd00db is one such pair: 8.4 at dichromacy, 7.9 at severity 0.8,
and it passed the gate.
MACHADO ships Table 1 of Machado, Oliveira & Fernandes (2009) for protan and
deutan at severities in tenths, and simulate_anomalous reads it. The
separation row now takes the worst over ANOMALOUS_SEVERITIES alongside the
existing dichromacy reading and names the severity its verdict came from.
Three decisions here were settled by measurement rather than by assumption, and each has a test.
- The matrices belong on linear light. The published table does not state a
transfer function. Machado calibrates severity 1.0 against the same
Brettel/Vienot dichromacy this file already uses, so the domain that
reproduces it is the domain the table is written for: on 4000 random hues the
severity-1.0 matrices land within a mean 2.84 dE (protan) and 2.44 (deutan) of
simulatewhen applied to linear light, against 3.89 and 4.97 on gamma-encoded sRGB. Getting this backwards would have put an error of that size under every number the feature produces. - 1.0 is left out of the sweep. It is dichromacy, which
simulatealready covers with the matrices every number in the style guide was measured on. Reading it twice under two models would have moved published figures for a view already gated. - Protan and deutan only. The repository already reports tritan without gating it, and this model's own reference implementation notes that it does not do tritanopia well. A tritan severity table would be spending credibility on the one form neither model is validated for.
The four matrices quoted in the suite were read off the authors' own page and are asserted against the shipped constants, because the table is the whole substance of this and a transcription slip would be a wrong answer wearing a citation. The bundled cycle's worst adjacent pair reads 15.8 dE under the sweep, which is what says the stricter reading is not a floor nobody can satisfy.
New gate: banking to 45 degrees. The aspect ratio has been in
choosing-a-form.md since that document existed and nothing measured it, which
is the shape of guidance this project exists to replace.
The failure is a resolution failure and it is measurable. On a saw wave whose decay limbs alternate between two rates, one exactly twice the other: at 2.4 x 5.2 inches the two limbs land 1.6 degrees apart on the page and the alternation cannot be seen at all; at 6.4 x 1.9 they land 10.6 degrees apart and it is the first thing you see. Same data, same axes, same limits. Both numbers are asserted in the fixtures, so a change that stopped the tall figure collapsing the rates fails the test that calls it a defect rather than quietly testing nothing.
GATES gained a row and every row after Line weight moved down one, which is
a break for anything that indexes that tuple rather than reading it by name;
audit() returns 21 rows now and not 20.
check_banking reads the median absolute segment slope of each panel's strokes
in display space, and is advisory. BANKING_SLOPE_MAX = 10.0 is a factor of ten
either side of banked - a typical segment past 84 degrees or under 6 - which is
a panel essentially vertical or essentially flat over its own typical step. The
band was picked against the corpus rather than argued: the 14 series in
examples/ that this gate reads span 0.19 to 2.95, so [0.25, 4] would have
fired on one of them and [0.1, 10] leaves the nearest legitimate case a factor
of 1.9 clear. The gallery test now asserts no banking warning, because an
advisory row does not fail a run and an over-firing advisory would have been
invisible there.
Four exclusions, each measured rather than reasoned into existence. A line with
linestyle="none" draws marks; the orbit figure's 168000-point cloud is one. A
fixed aspect is a statement about the data. Under BANKING_MIN_POINTS = 8
vertices is furniture rather than a rate, and the corpus has 24 such strokes. An
x that does not run one way is a parametric curve, where the typical slope is
not a rate of anything. Slopes come off the authored vertices and not the
densified stroke, because densifying makes every segment 2px and the median of
that measures the densifier.
step, stackplot and contour sets are read now. The last notes left these
three as geometry the attribution harvest does not reach, and each was unread
for its own reason.
ax.step keeps the points it was handed and draws a staircase through them, so
densifying get_xydata lays the harvested geometry along the diagonal chord of
every riser. Measured on a six-point square wave: 836 harvested points, 785 of
them on blank page. _drawstyle_xy runs the vertices through the pts_to_*step
helpers in matplotlib.cbook, which is what Line2D itself does, rather than
writing a second staircase that can disagree with the first. A test asserts
those helpers still resolve, because a rename upstream would not raise - it
would mean "this line has no drawstyle" and quietly revert every step plot to
its chords.
stackplot bands and contour sets carry paths and no offsets, so _series_px
returned None for them and the offsets branch was the only branch. _path_px
reads Path.to_polygons, not path.vertices, because the dummy vertex a
CLOSEPOLY carries and the jump a MOVETO makes are not points on the stroke -
the same bridging defect NaN handling exists to avoid, one level down.
Filled series are judged on containment rather than on distance to their
outline. stackplot hands neighbouring bands the same dividing edge, so on
boundary distance a label inside the upper band is exactly as far from the lower
band's outline as from its own and every stacked label reads as ambiguous.
A fill has to carry a legend-visible label to count as a series and a stroke
does not, which is the one asymmetry here and it is deliberate. A confidence
band lies on top of the curve it belongs to, so counting an anonymous
fill_between puts a competitor at distance zero from every direct label on
that curve. stackplot(labels=...) and a deliberate fill_between(label=...)
are series; _child3 is a band bound to somebody else's line.
A mark eclipsed by a mark that is not its nearest neighbour was not
overplotting. The last notes named this as the case no 1-NN test reaches and
left it. Contact is d < r_i + r_j, and the j that minimises d need not be
the j that maximises r_j, so a mark clears its nearest neighbour and is
swallowed whole by a larger one further off. Measured on 60 marks - 40 small
ones in pairs 8px apart, each pair under a 120px disc centred 20px away - every
mark is in contact, 40 of them do not appear in the render at all, and
check_overplotting returned "no scatter overplotting" off a 33% reading.
Rendered coverage was the fix those notes proposed and it is not the one this
takes, because the predicate was already exact and only asked of the wrong
neighbour. _contact_fraction asks it of every neighbour. Where radii are
uniform the nearest one still answers it outright, since r_i + r_j is then a
constant and "some mark is within it" and "the nearest mark is within it" are
the same statement; that keeps the common case on one k=2 query, and a test
pins the two paths to the same number rather than trusting the argument. Where
radii differ, candidates come out of one range query at 2 * r_max, which
cannot miss a touching pair, and each is filtered on its own two radii.
The numpy fallback got the same treatment, because CI installs no scipy and a
gate fixed only where scipy is present is fixed nowhere that matters. A short
size list is now tiled over the offsets the way a Collection cycles it, so
the radii the gate reads are the radii it drew.
Readability was measured over page the label does not sit on. The oriented
box landed in check_collisions and check_text_readability was left sampling
the axis-aligned block, which the last notes said out loud and left open. On one
45-degree 11pt string that block is 191.5 x 191.5, 36669 pixels, around an
oriented box of 239.5 x 31.3, 7505: four fifths of what was sampled belonged to
the label only through its bounding box. Six strokes laid in the empty
upper-left triangle, none of them touching a glyph, were reported as data ink
over 14% of the label's box.
_oriented_mask rasterises _corners over the sampled block, and both clauses
now read through it. The clutter fraction counts edge pixels inside the box
against the box's own area, and the contrast quantile draws from the same
pixels, so a dark field in a corner the label never reaches no longer sets the
verdict for a string on light ground. The mask is applied after the blur rather
than before, because the local average is what says whether a pixel is an edge
and a stroke entering from outside has to be compared against its neighbours out
there.
Upright labels are handed None and stay on the code path they were measured
on: _corners returns the axis-aligned box for them, so a mask would only shave
off the 1px ring the slice adds, and that is a number nobody measured. The same
strokes moved onto the glyphs still fail at 95%, which is what says the false
positive went without the gate going with it.
Label attribution measured against strokes that are not on the page, and did not measure against half the ones that are. Two defects in the same gate, both of them about what counts as a series.
- A break in the data was bridged.
_polyline_pxdropped non-finite vertices and then densified across what was left, which joins the two sides of every hole. A 100-point sine withy[40:60] = nancame back with 326 invented points strung across blank page, and a label sitting in that gap was judged against a curve that is not there. Masked arrays arrive the same way, becauseLine2Dfills a masked input with NaN on recache. Densifying per run of consecutive finite vertices fixes both spellings. - Only
ax.lineswas read. A point cloud could not own a direct label and could not be the neighbour that made one ambiguous, so a label sitting on top of a dense scatter passed clean._series_pxnow takes scatters too, recognised by carrying sizes, which is the discriminatorcheck_overplottingalready uses and which keepsfill_betweenfrom planting a phantom series at data (0, 0) off its single zero offset.
step, stackplot and contour sets were left unread here - PolyCollection and
LineCollection geometry rather than offsets, a different harvest than this one.
They are the first entry above.
Text collision compared the boxes rotation left behind, not the boxes.
get_window_extent returns the axis-aligned bounding box of the rotated
string. Measured on one 11pt label: 119.0 x 15.3 at 0 degrees, 15.3 x 119.0 at
90, and 94.9 x 94.9 at 45. That last one is five times the ink, and the extra
area is two right triangles nothing is drawn in. Two parallel 45-degree labels
with clear page between them were reported as colliding, which is the shape of
false positive that teaches people to skim the row.
_corners reconstructs the oriented box without private API or a rebuilt
transform: rotating a rectangle about any point sends its centre to the centre
of the result, so the centre of the rotated AABB is the centre of the oriented
box, and the unrotated extent supplies the sides. The reconstruction is checked
rather than trusted, and anything that does not round-trip to the extent
matplotlib reported falls back to the axis-aligned corners. _overlap is now
the separating axis theorem over four edge normals, which is exact for
rectangles and gives the old min/max answer whenever both boxes are upright.
check_clipping was left alone and a test says why. An AABB is the bounding
box of the oriented box's own corners, so its extremes are attained by real
corners of the label and a min/max test against the canvas gives the same
answer on either shape. Rotation costs that gate nothing. check_text_readability
sampled the axis-aligned block, and masking it to the oriented box was a further
change; it is the first entry above.
The contrast clause read a smooth backdrop as its own average, through the
branch written to stop it doing that. _worst_backdrop binned a label's box
on pix // 8 and took the worst bin covering at least
TEXT_BACKDROP_MIN_SHARE. On a figure made of flat fills that is right. On a
smooth one an 8-cube splits the ramp into dozens of bins, none of them reaches
the share floor, and the function falls through to pix.mean(axis=0) with
nothing in the output saying it did. Measured on a viridis ramp under a 30x600
box: 76 bins, a 3.5% mode, a verdict of 4.25:1 exactly equal to the box mean,
against a true worst pixel of 1.34:1 and a true tenth percentile of 1.63:1. Its
own docstring named the mean as the wrong summary and the fallback returned it.
Contrast is defined per pixel, so the quantile was available directly and the
binning was only ever standing in for it. The gate now reports the contrast the
text holds over all but the worst tenth of its box, and there is no fallback
branch because no case reaches one. TEXT_BACKDROP_MIN_SHARE keeps its value
and its meaning: a backdrop covering a tenth of the box sets the verdict, a
handful of stray antialiased pixels does not.
_contrast_field_255 vectorises the existing scalar helper rather than
restating WCAG contrast, and test_contrast_field_agrees_with_the_scalar_helper
walks a spread of colours through both so they cannot drift. All seven gallery
figures still pass, including the viridis field with 31 strings on it, which is
what says the stricter reading does not over-fire.
scatter(s=...) is not an area, and two gates were built on the assumption
that it is. matplotlib documents s as "the marker size in points**2". The
unit marker path is a circle of radius 0.5 scaled by sqrt(s), so the drawn
diameter is sqrt(s) points and the drawn area is pi * s / 4. Measured, not
inferred: at 200 dpi scatter(s=100) and plot(markersize=10) each lay down
741 pixels of ink. scatter_diameter_pt now carries the conversion, and
test_scatter_size_is_a_squared_diameter_not_an_area pins it against
matplotlib rather than against a docstring.
- Mark ratio reported 1.3x on two marks of identical drawn area. The 4/pi
bias the 0.3.0 notes describe was corrected on the
markersizeside and left standing on thesside, so the ratio it printed was wrong by exactly the factor that release set out to remove, on exactly the figures it named. Both operands now convert to the area of the disc actually drawn, and the row reports that area rather than a raws. - Overplotting needed the marks to be roughly 1.8x past contact before it
said anything. Two errors compounded: the radius came from
sqrt(s / pi), 12.8% too large, and the comparison wasnn_dist < radius_px, which is the condition for a mark's centre to be swallowed rather than for two marks to touch. A grid of 64 discs each overlapping its neighbours by a quarter of their diameter renders as one solid square and returned "no scatter overplotting". Contact isd < r_i + r_j, and the neighbour's own radius now comes from the index the query already returned, so a big mark beside a small one is judged on both.
A case no nearest-neighbour test can reach - a small mark covered by a large one that is not its nearest neighbour - was left standing here and is the second entry above.
Alt text is swept for the numbers it states. tests/test_docs_match_code.py
already held every description on the site to the string the example attaches,
so the page could not drift from the code. Nothing read either against the
picture, and three figures described something the code does not draw:
- the slope graph said
eleven of twelve rise. All twelve rise, and always have:afteradds a normal centred at 0.11 with a spread of 0.05, so a fall needs a draw 2.2 sigma low, and under seed 4 the smallest gain is 0.047. - the demo said the Bayesian run
reaches 0.05 by epoch 6. At epoch 6 that curve is at 0.115, and 0.05 arrives at epoch 6.9. - the field said
a 28-step gradient descent path from (-1.9, 2.2). The loop runs 6000 steps from (-1.75, 2.15). None of the three numbers was the figure's, and one of them, 2.2, is the panel's x limit, so a resolver reading the sentence loosely would have called it correct.
tests/test_alt_text_numbers.py builds every described figure and sweeps its
description: each number either resolves against a count, limit, tick or extreme
the figure has, or names a computation that confirms it, or sits in a ledger with
the reason nothing can. The relational claims get checkers of their own, because
a number that is right about the figure and attached to the wrong curve is the
defect here. The three PNGs whose description changed were rebuilt so the
metadata a screen reader reads is the corrected text.
A claim the last audit retracted was still shipping in a gate message.
"ACM and Elsevier reject the submission" was corrected in the style guide alone;
SKILL.md and check_figure.py kept it, the module in the message printed under
every Type 3 figure. RETRACTED_CLAIMS in tests/test_prose_claims.py now holds
a retraction out of both documents and modules at once, with the wording to use
instead, because a retraction that lives in one file is one the next writer
copies back from another.
The prose sweep went red the moment somebody wrote release notes. 0.6.0
fixed a suite that failed at every tagged commit by putting ## Unreleased in
the unresolved ledger. The ledger has a test asserting none of its entries
resolves, so the failure moved rather than went: it now fired on every commit
where the heading existed, which is every commit a maintainer writes notes in.
The heading is defined by the release process rather than by a document, exists
in exactly one of the two states, and now resolves in both.
Every threshold is a module-level constant, as the README has said since
0.2.0. Nine were not: the ink-detection cutoff, the two WCAG large-text sizes,
the numeric bold weight, the placement warning and the opaque-mark definition in
check_figure.py, and all three ordinal rows of check_palette.py, whose
categorical siblings have sat at module level throughout.
tests/test_thresholds_are_constants.py sweeps both modules for a comparison
against a literal, recognises the structural ones by shape, and requires the rest
to name a constant or a reason. Values are unchanged, so no verdict moves.
0.6.0 — 2026-07-30¶
What changed¶
- The README is a landing page. The reference material moved to
docs/gates.mdanddocs/getting-started.md, both authored pages named inAUTHORED. Nothing was duplicated in the move. docs/api.mdadded::::directives read by mkdocstrings at build time, documenting fifteen functions. Eight of them gained a docstring.tests/test_api_reference.pyholds the page to the modules.PROSE_DOCSis derived from git rather than listed: every tracked markdown file, minusCHANGELOG.mdandspecs/, which are exempt by a rule and not a list. Six resolver domains added, taking 229 unresolved spans to 23.- Three tools added to CI: ruff's
DOC102,DOC202,DOC403,DOC502;griffe checkagainst the last tag, failing only when a break is not mentioned in the Unreleased section; andcodespellwith three ignore-words.pymarkdownlntwas measured and rejected. uv run bump-my-version bump minorrewritesCHANGELOG.md,pyproject.toml,plugin.jsonandrecipe.yaml, commits, and tagsv<new>.CHANGELOG.mdis first in the file list and the order is load-bearing.tests/test_version_sites.pyadded, holding the bump config to the files it points at.examples/demo.pyandexamples/gallery.pytake an optional output directory. The default is unchanged.- The docs build installs
--only-group docsinstead of naming its dependencies inline. make auditadded, withspecs/2026-07-30-standardized-docs-audit.mdrecording what each check proves and what it does not.conda/README.mddescribes a submission that has happened rather than one that is planned.- Em dashes removed from the README and the pages cut out of it.
Why it changed¶
The README is a landing page now, and the documentation is on the docs site. It had grown to 361 lines carrying both threshold tables, three install routes, the usage examples, the retina history and the design notes, for a project that has published a docs site since 0.4.0. Someone deciding whether to use this had to read the reference material to find out what it was.
Nothing was duplicated in the move, which is the only version of this worth
doing. docs/gates.md is the one copy of the two tables and the roster prose;
docs/getting-started.md is the one copy of install, the two settings that need
your document's values, the usage examples and the requirements. Both are
authored pages in the sense docs/gallery.md already was, and AUTHORED in
tests/test_docs_site.py names them so that a page becoming a hand-maintained
copy still fails.
The gates that read the README read those pages instead. Eleven parsers and
seven roster-count claims were pointed at one file; the count claims now carry
the document each is made in, because the reason they exist is that one copy of
a claim gets updated and the others do not. docs/api.md had been sending
readers to tables on the home page that are no longer there.
Em dashes are gone from the README and from the pages cut out of it.
Comments naming the README were swept. A dozen of them cited it as the
source of a promise that had moved: three files and no install, the Python 3.8
claim the stdlib-only CI job exists to keep true, the test count
tests/test_docs_render.py explains its collection strategy against. One named
_compares_all_pairs, a function renamed to _axes_all_pairs long enough ago
that nothing in the repository still used the old name.
The prose sweep failed on every release and nobody had run it on one.
CONTRIBUTING.md tells a maintainer to write release notes under a
## Unreleased heading, and the heading resolver added in this cycle checks
that a heading named in prose exists. It does, right up until the bump renames
it to the version, so the suite went red at the tagged commit and green again
with the next change. The absence is correct and load-bearing: it is what makes
a release with nothing written about it stop before the tag. The span is in the
unresolved ledger with that reason.
The documentation audit is a procedure now, not a memory. It had been run
four times, each time reconstructed from the previous run's changelog entry, and
each run missed something the next one found: seven of eleven prose documents
unswept, a fourth version site nobody had listed, a docs dependency list that
existed twice. make audit runs every mechanical check in one command, and
specs/2026-07-30-standardized-docs-audit.md records what each one proves and
what it deliberately does not.
The prose corpus is derived from git rather than listed. PROSE_DOCS was
four hand-written paths; it is now every tracked markdown file, resolved through
the docs/ symlinks and deduplicated, minus a historical class.
CONTRIBUTING.md, SECURITY.md, conda/README.md, docs/gallery.md and
docs/api.md were making unchecked claims about the code with the suite green.
CHANGELOG.md and specs/ are exempt, by a rule and not a list. A changelog
entry saying check() returned (rows, ok) is accurate history — it did, until
0.4.0 — and sweeping it against today's modules would turn a correct record into
a failure whose only fix is to falsify it. Two tests keep the exemption from
being a hiding place: one names the documents the rule currently catches, and
one requires each of them to carry the date it is a record of.
Six resolver domains were added so the new documents could be checked rather than excused: tracked files anywhere in the repository, markdown headings, TOML tables and keys, dependency groups and distributions, CI job and step names, and test-suite symbols. The first run over the full corpus left 229 unresolved spans; the domains took that to 23, of which 22 are conda-forge's names or placeholders and are in the ledger with the reason.
The twenty-third was a bug in the sweep rather than a defect in a document.
A span written with doubled backticks, which is how markdown shows a literal
backtick, matched as empty and reported '' as an unresolvable claim. The
doubled form is matched first now and its contents swept in their own right.
The CI domain had to be written twice. The first version accepted any word of
five characters or more occurring anywhere in the workflow files, which resolved
the bare word status — the third field of a gate's row triple, nothing to do
with CI. A resolver that agrees with almost anything reports agreement with
nothing. It reads job ids and name: values only.
Three tools, after checking whether any of this was already somebody's
library. Ruff's DOC102, DOC202, DOC403 and DOC502 fail on a docstring
that names a parameter the signature does not have, or documents a return, a
yield or an exception the body never produces — the same defect class the
markdown sweeps look for, on a surface they cannot reach. The rules that flag an
absent section are not adopted: DOC201 alone reports 59, and asks for a house
style this project does not write in.
griffe check compares both modules against the last release tag. It is not a
veto, because a 0.x project may break its API; the new CI job fails only when a
break is not mentioned in the Unreleased section. check_palette.py is meant to
be vendored by copy, so a renamed function does not break a resolver, it breaks
a file somebody pasted into their repository six months ago.
codespell reads the words, which nothing else here does. Three ignore-words,
each a term the documents are right to use: vermillion is the Okabe-Ito
palette's own spelling, commun is an abbreviated journal title, and theses
is the plural of thesis.
pymarkdownlnt was measured and rejected. It finds two things on the whole
corpus and misses the accidental-heading defect this project hand-rolled: given
a hex color wrapped mid-span, it reports a missing top-level heading and does
not notice the <h1> that was invented.
The docs build carried its dependency list twice. The build step ran
uv run --no-project --with "zensical>=0.0.51,<0.1", which is the docs
dependency group written out again in a file nothing resolves against
pyproject.toml. It was correct only while the two happened to agree, and they
stopped agreeing the first time the build needed a package one of them did not
name: the group gained mkdocstrings-python for the API page, that line did
not, and CI failed with No module named 'mkdocstrings' after the same build
passed locally in an environment that already had it. --only-group docs now,
with three gates: the build step has to install the declared group and may not
name a package inline, the group has to contain the builder, and a page using
::: directives has to be matched by a handler in the group.
The docs site has an API page, and it is not written by hand. docs/api.md
is ::: directives; Zensical's mkdocstrings extension reads the signatures and
docstrings out of skill/scripts/ when the site builds, so a default shown
there is the default the code has. A hand-written reference would have been a
second copy of every signature, which is the drift tests/test_prose_claims.py
already exists to catch one level down.
Fifteen functions, chosen rather than swept: audit, report, describe,
alt_metadata, page_scale and content_width_pt from check_figure, and
check, cmap_kind, cmap_back_travel, contrast, delta_e, simulate,
hex_to_linear, linear_to_oklab and relative_luminance from
check_palette. The twenty gates are deliberately absent: audit() computes
the renderer, canvas and scale arguments they take, so calling one directly
means reproducing that, and what a caller needs from a gate is the threshold
and the failure condition the README tables already carry.
Eight of those fifteen had no docstring and now do. Writing them turned up a
stale one: audit() said check_palette.check "returns its pair the other way
round, as (rows, ok)", which stopped being true in 0.4.0 when the two were
made to agree. The README and check() itself both record the change; the
docstring at the call site was the copy nobody updated, and it was wrong for
two releases.
tests/test_api_reference.py holds the page to the modules: every public
callable is documented or named in EXEMPT with a reason, every directive
names something that exists, and every documented name has a docstring, since
::: on a bare function renders a heading over an empty block. Coverage is
what the tests are for -- a public function added to either module would
otherwise appear nowhere, with no build error, leaving an incomplete reference
that reads like a complete one.
conda/README.md described a submission that had already happened. It read
as a plan -- "that costs one manual submission to staged-recipes" -- while
conda-forge/figure-gate-feedstock had existed since 2026-07-30 and the
channel was serving 0.4.0. Anyone following it would have opened a second
staged-recipes PR for a package conda-forge already builds.
It now says where the package comes from, that the feedstock's own
recipe/recipe.yaml is the copy that builds and this one is not, and what
maintainer access does and does not change: the autotick bot produces the
version bump either way, and being a maintainer decides who merges it. The
admin-bot commands are written down, including
@conda-forge-admin, please add bot automerge, and the submission steps are
kept as a record rather than as instructions.
One command moves the version. It is written in four files and a tag, and
until now nothing wrote them together. 0.5.0 is what that cost: the bump moved
pyproject.toml and skill/.claude-plugin/plugin.json, and all three pytest
jobs failed on the release PR because conda/recipe.yaml still said 0.4.0.
uv run bump-my-version bump minor now rewrites CHANGELOG.md,
pyproject.toml, plugin.json and recipe.yaml, commits, and tags v<new>.
Pushing the tag still publishes; release.yml has not moved.
CHANGELOG.md is first in the file list, and the order is load-bearing.
bump-my-version writes each file as it reaches it rather than validating the
set first, so with the changelog last a missing ## Unreleased heading leaves
the other three bumped on disk before it errors. First, it touches nothing. The
failure itself is deliberate: a release with no notes written for it now stops
before the tag rather than at the no '## $version' section check in
release.yml, which runs after the tag is already pushed.
tests/test_version_sites.py holds the config to the files it points at:
current_version against the project version, tag_name against what
release.yml triggers on, and each search pattern against the file it claims
to find it in. The last one is the reason the test exists. bump-my-version does
refuse to write a file whose pattern is missing, but only when someone runs it,
which is the moment a release is being cut. CHANGELOG.md is exempt from that
check, since ## Unreleased is absent for most of the life of the repository
and present only once there are notes.
The two checks that caught the 0.4.0 recipe stay. What changes is their job: they stop being the only thing between a half-finished bump and a release, and become the proof that one command ran.
pytest no longer rewrites the eight committed example PNGs.
tests/test_example.py runs examples/demo.py and examples/gallery.py as
subprocesses, because a README whose first code block crashes is worse than no
README. Both scripts wrote beside themselves, and the PNG bytes depend on the
fonts installed locally, so every run left eight modified files in the working
tree. A git add -A then swept a binary diff into whatever commit came next,
which is how eight unrelated PNGs reached the 0.5.0 release branch.
Both scripts now take an optional output directory,
python examples/demo.py [output-directory], and the tests pass tmp_path.
The default is unchanged: run either one by hand and the files land beside it,
which is what the README promises.
test_running_the_scripts_elsewhere_leaves_the_committed_pngs_alone runs both
and compares the committed files before and after, so a directory argument that
is accepted and then ignored fails even though the other tests would still pass.
0.5.0 — 2026-07-30¶
What changed¶
- The repository is a Claude Code plugin marketplace.
/plugin marketplace add narenp12/figure-gateinstalls the skill. Two CI checks come with it, both in theskilljob. - Ruff and mypy run in CI. Neither existed before. Thirteen findings were fixed
rather than suppressed; two carry a
noqawith the reason beside it.per-file-target-versionreadscheck_palette.pyagainst the 3.8 grammar, andE741is ignored becauselis the OKLab lightness channel. _back_traveltakes direction from net travel,ls[-1] >= ls[0], rather than by majority vote over the steps. No named colormap changes kind.
Why it changed¶
The repository is a Claude Code plugin marketplace.
.claude-plugin/marketplace.json lists the skill and skill/.claude-plugin/plugin.json
describes it, so /plugin marketplace add narenp12/figure-gate installs it and
follows the tags this project already cuts. The route that existed before was
cp -r skill ~/.claude/skills/, which pins nothing and updates never. Nothing
publishes: the marketplace resolves against git, so pushing is the release.
Two CI checks come with it, both in the skill job. plugin.json carries its
own version and Claude Code pins installs to that string, so a release that
bumped pyproject.toml alone would ship new files under the old version and no
installed copy would ever update. The second check resolves each marketplace
entry to a real plugin directory with a matching name, because a broken
source is otherwise found by a user whose /plugin install fails.
Ruff and mypy run in CI. Neither existed before. The reason for ruff is one
file: check_palette.py is claimed to run on Python 3.8, and that claim is what
makes it vendorable into a non-Python toolchain. The stdlib-only job proves
the two invocations it makes still run there; per-file-target-version sets
that one file to py38 and reads all of it against the 3.8 grammar. Ruff is
configured to ignore E741, since l is the name of the OKLab lightness
channel and linear_to_oklab returns l, m, s because that is what the
published matrix calls its rows.
Thirteen findings were fixed rather than suppressed: four dead imports, a
pytest.importorskip whose binding was unused, two percent-format strings, an
f-string with no placeholders, two unused loop variables, a missing
raise ... from None, and one annotation mypy needed. Two carry a noqa with
the reason written next to it.
cmap_kind called a windowed viridis "misc". _back_travel picked its
direction by majority vote over the steps, counting strictly positive steps
against the length of the whole list. Plateau steps therefore counted as
evidence against ascending, and 8-bit sRGB rounding makes plateaus the majority
whenever the lightness span is narrow relative to the sample count. Viridis
windowed to t ∈ [0.00, 0.38], the window style-guide.md asks for beside
status green, is 158 plateaus in 255 steps: the vote read it as descending and
scored every genuine rise as back travel, 1.00 against a 0.02 threshold.
The bug was one-sided, which is why it survived. A descending ramp with the same
plateaus landed on -1 by accident and passed, so only ascending ramps failed.
Direction is now net travel, ls[-1] >= ls[0], which is what the vote was
approximating. No named colormap changes kind.
0.4.0 — 2026-07-29¶
What changed¶
check_palette.check()changed what it returns:(ok, rows), matchingcheck_figure.audit(). It returned(rows, ok)before. If you unpack it, swap the names.requires-pythonchanged>=3.9→>=3.11.check_palette.pystill runs on 3.8 when vendored, and matplotlib stays floored at 3.8.GATESadded: one registry holding the twenty rows with their functions, advisory flag and arguments.ADVISORY_GATESis derived from it.audit()andcheck()gained docstrings. They were the only functions in either module without one.NO_GUIDANCEis empty:ClippingandInk coveragehave guidance, with a test to keep a future re-entry deliberate.tests/test_prose_claims.pyadded, sweeping the four prose documents.EXTERNAL_CLAIMScarries claims about the world with a source and a date.KNOWN_DISAGREEMENTSis compared only against colormaps the running matplotlib has. A broken cmasher skips with its reason instead of erroring.conda/recipe.yamlandconda/update_recipe.pyadded, withtests/test_conda_recipe.pyholding the recipe topyproject.toml.- Corrected: RdBu's poles (
#b1182band#2065abare t=0.098 and t=0.899, not the ends), fiveCMAP_*constants attributed to the wrong module, Cleveland & McGill's ordering, the ACM/Elsevier claim, and the uncited 99.81% figure.
Why it changed¶
A minor release because it breaks a call. check_palette.check() returned
(rows, ok) while check_figure.audit() returned (ok, rows), and the README
carried a paragraph warning readers about the difference. Documentation
standing in for a fix: unpacking either one the wrong way binds a bool to the
rows and raises nothing at the call site, so the failure surfaces later,
somewhere else, as a bool that will not iterate.
Python 3.11 is the floor. requires-python was >=3.9, and 3.9 reached
end of life on 2025-10-31, so the package was being offered to an interpreter
upstream had stopped patching. 3.10 goes the same way in October 2026, so the
floor skips it. Two things deliberately did not move with it:
check_palette.pystill runs on Python 3.8 when vendored, which is what the file is for, and CI still proves it in a job that installs nothing. Installed from PyPI it needs 3.11, because the package carriescheck_figure.pytoo.- matplotlib stays floored at 3.8. Pinned matplotlib is normal in scientific environments, the checks are written to survive the 3.8-to-3.11 API drift, and the CI leg that pins 3.8.4 now runs under Python 3.11 rather than disappearing.
check() now returns (ok, rows). If you unpack it, swap the names. The
paragraph in the README is gone and a test holds both entry points to the same
shape.
Prose is now swept, not spot-checked¶
An accuracy audit of the reference material found five defects the doc suite could not have caught, because every assertion in it was written after somebody noticed the claim. Two were mechanical and are now mechanically prevented:
#b1182band#2065abwere described as RdBu's poles. They are the map at t=0.098 and t=0.899. Its actual ends,#67001fand#053061, fail the lightness band, and the dark blue also fails the chroma floor. A reader taking two swatches off the ends got a failing pair. The section now states a sampling window, the same shape as the viridis rule beside it.- Five
CMAP_*constants were named in a paragraph aboutcheck_figure.py. They are defined incheck_palette.py, which is where a reader porting the checks needs to look.
Three were claims about the world, which no test can verify: Cleveland & McGill's ordering was printed with seven ranks and a rank the paper does not contain, "ACM and Elsevier reject the submission" overstated what either publishes, and the 99.81% alt-text figure was correct and uncited.
tests/test_prose_claims.py sweeps the four prose documents: every code span
has to name something that exists, every hex has to be a colour something
ships, every fenced python block has to parse, every sampling window has to be
one the repo defines, and a constant named in a paragraph about one module has
to be defined in that module. Claims about the world go in EXTERNAL_CLAIMS
with a source, a date and the passage that supports them, and the cited work
has to appear in the document's own references. Anything a resolver cannot
place is named in a ledger with the reason.
Clipping and Ink coverage have guidance¶
NO_GUIDANCE held the two gates the reference material never explained, on the
argument that both were mechanical rows with nothing to advise. Both turned out
to have something a reader could not get anywhere else. Clipping's two natural
fixes are shrinking the type, which moves the failure to the Type size gate,
and bbox_inches="tight", which fails nothing while trimming the canvas away
from the authored width that every legibility number is derived from. Ink
coverage is routinely read as Tufte's data-ink ratio, which it is not, and
which it moves opposite to under the edit that reading suggests.
The set is empty now, with a test to keep a future re-entry deliberate.
Standardization¶
- One gate registry.
GATESholds the twenty rows with their functions, their advisory flag and the arguments they need.audit()builds its rows from it andADVISORY_GATESis derived from it, where both were separately maintained lists of the same names. - Both entry points are documented.
audit()andcheck()were the only functions in either module with no docstring. - Remediation clauses are enumerable. Fifteen of twenty gate messages end
in a
<-clause naming the fix. The five that do not are listed in the test suite with the reason, rather than being an invisible inconsistency.
The oracle no longer depends on which matplotlib you have¶
KNOWN_DISAGREEMENTSis scoped to the registry it is about.test_only_the_three_known_colormaps_disagree_with_cmasherasserted that all three of its adjudicated colormaps still disagree. Two of them,managuaandvanimo, arrive in matplotlib 3.10, so under the 3.8.4 floor this project still supports the test read their absence as a resolved disagreement and failed. CI never saw it, because cmasher is installed on the latest-matplotlib job only;uv sync --group devwith an older matplotlib pinned did.
Same defect class as the swatch sweep: an expectation derived from a registry, written down as a constant. The constant stays, because each entry is an adjudication that has to live somewhere, and it is now compared only against the colormaps the running matplotlib actually has. A second test holds every key to a real name on 3.10 and up, so scoping cannot quietly swallow a typo.
- A broken oracle skips with its reason instead of erroring. cmasher 1.9.2
builds each of its 114 colormaps with
ListedColormap(..., N=...), deprecated in matplotlib 3.11 and removed in 3.13, which is what those 114 identical warnings on every test run were counting down to. When 3.13 lands, cmasher stops importing at all, through no fault of anything here. The differential now reports that as a skip naming the ImportError and the matplotlib version, rather than a suite that fails on someone else's deprecation. The warnings are filtered with the countdown written next to the filter; nothing underskill/scripts/constructs aListedColormap, so the filter cannot hide a defect of this project's.
A conda package¶
conda/recipe.yaml is a rattler-build v1 recipe for conda-forge, so the install
line will be conda install -c conda-forge figure-gate with no extra channel to
add. Submission is one manual PR to conda-forge/staged-recipes after this
release reaches PyPI; the autotick bot opens the version bump on every release
after that. conda/README.md is the checklist, and
conda/update_recipe.py stamps the version and the sdist hash, downloading and
hashing the sdist itself rather than trusting PyPI's declared digest.
Nothing in this repo builds it, which is precisely why tests/test_conda_recipe.py
exists: it holds the recipe's version, runtime dependencies, Python floor and
entry points to pyproject.toml. A conda package that disagrees with the wheel
about any of those is a defect only a conda user meets, and they meet it as "the
gate does not run" rather than as a build failure. The recipe depends on
matplotlib-base, not matplotlib, which on conda-forge is the difference
between the library and a package that pulls pyqt for a backend these checkers
never open.
The README claimed no conda install at this release, because there was not one
until the staged-recipes PR merged. It has since merged, and the README gained
the badge and the conda install -c conda-forge figure-gate line after 0.4.0
shipped.
0.3.0 — 2026-07-29¶
What changed¶
- New gate:
check_colormap, row 18, a hard failure.Fontsmoves to 19 andAlt textto 20. A heatmap drawn injetwas a PASS in every release before this and is a FAIL now. cmap_kind()added tocheck_palette.py, stdlib only, withCMAP_SAMPLES = 256,CMAP_QUALITATIVE_N = 40,CMAP_SPAN_MIN = 0.02,CMAP_BACKTRAVEL_MAX = 0.02andCMAP_WRAP_DE_MAX = 3.0.miscis the only outcome that fails;jet,rainbow,hsvandgist_ncarland there.- A qualitative colormap is routed to the palette gates for its separation rows only.
ANONYMOUS_CMAP_NAMESadded, holding all three spellings matplotlib uses for an author-built colormap.- A seventh gallery figure,
gallery-encoding.png. - Twenty-two swatches added across the style guide, gated at source and at
paint.
palette.cssreaches the page again: the scheme rules no longer carry a:rootprefix that matched nothing. GUIDANCE_ANCHORSadded, binding eighteen of the twenty gates to a passage.ClippingandInk coverageare named in an exemption set.- The style guide gained a references section: Kovesi, Crameri et al., Nuñez et al., Moreland.
- The README's Threshold column is resolved against the modules. Two prose rows were converted to checkable numbers; seven remain a literal set.
test_palette_oracle.pyskips per test rather than at collection, so the test count is the same everywhere. The cmasher differential runs in CI.mainis branch-protected: fourteen required checks, enforced for admins.plans/is untracked.specs/stays.- Suite: 286 → 482 tests. Gates: 19 → 20.
Why it changed¶
A minor release, for the same reason 0.2.0 was one: a figure that passed on
0.2.0 can fail on this one. There is a twentieth gate, and it is a hard failure
rather than an advisory. A heatmap drawn in jet was a PASS in every release
before this and is a FAIL now.
The four sections below are the release in the order it happened: a gate, the site it was published on, an audit of the documents it arrived with, and the two ways the suite stayed green while CI was red.
A twentieth gate: colormap kind¶
Every gate before this one read artists that carry an identity: a line's
colour, a bar's face, a scatter's marks. A figure whose entire content is one
colormapped image has no such artist, so it passed every check by having nothing
the checks knew how to read. _data_colors_by_axes had excluded colormapped
artists since it was written, with a comment saying they answer to "the viridis
rule instead". No such rule existed.
check_colormapis row 18, directly afterContour dash, which movesFontsto 19 andAlt textto 20. It harvests every artist inax.imagesandax.collectionswhoseget_array()is notNone, classifies each colormap, and fails the ones a reader cannot order values in.
The guard is the array, never the colormap. Every ScalarMappable carries a
default colormap whether or not anything was mapped through it: a plain
scatter(x, y, color="#0072b2") returns viridis from get_cmap() and
None from get_array(). Testing the colormap would gate every unmapped
scatter against a ramp it never used.
cmap_kind()classifies, incheck_palette.py, stdlib only. It samplesCMAP_SAMPLES = 256levels, converts to OKLab, and reads the lightness channel. UnderCMAP_QUALITATIVE_N = 40levels is qualitative. A span underCMAP_SPAN_MIN = 0.02is isoluminant and carries no order. Otherwise the measure is back-travel, the fraction of a segment's lightness span spent moving against its own direction: underCMAP_BACKTRAVEL_MAX = 0.02over the whole map is sequential, under it over both halves is diverging, or cyclic when the ends are withinCMAP_WRAP_DE_MAX = 3.0in OKLab ΔE ×100.
Everything else is misc, and misc is the only outcome that fails. jet,
rainbow, hsv and gist_ncar land there.
-
The cyclic wrap is a colour distance, not a lightness one, and that was found by running a differential rather than by reasoning. The first draft measured the wrap in lightness and put 11 of 148 colormaps in the wrong family. RdYlGn,
managuaand ninecmr.*maps were every one of them called cyclic by us and diverging by cmasher. A symmetric diverging map has equal lightness at both ends by construction, so lightness cannot separate the families. Only a cyclic map closes the loop in colour. The gap in end-to-end ΔE runs from 0.74 to 7.48, a factor of ten, and 3.0 sits near its geometric mean. -
A qualitative colormap is routed to the palette gates, read for its separation rows only, exactly as
check_series_colorreads them. The lightness-band and chroma-floor rows are for a palette being chosen, not for colours already drawn; applied here they fail Okabe-Ito, which this project ships. -
A seventh gallery figure,
gallery-encoding.png, because the gate needed one that could not be drawn any other way. Three complex-plane panels: Mandelbrot escape time in viridis with a colorbar, Newton basins forz³ − 1in three separated hues with a legend, and the phase of a rational function in twilight on a bar ticked at −π, 0 and π whose ends are the same colour because they are the same angle. The set's interior is drawn in an explicit neutral and keyed off the bar: "did not escape" is a separate class, not a small value.
Three dense images with three keys in one row is the hardest composition in
the gallery, which is why it is there. The one failure on the way was Text
collision, on a first attempt that put both keys through the x labels.
- Stated limits, because the row is named "Colormap kind" and not "Colormap
quality".
turbopasses as diverging: its lightness profile genuinely is diverging-shaped, and its real defect is hue banding, which a lightness-only measure cannot see.Wistiais classifiedmiscand is sequential by kind; back-travel divides by span, and narrow-span maps get noisy ratios. Both are written down inspecs/2026-07-28-colormap-kind-gate-design.mdwith the measurements, rather than resolved with a guessed constant.
The swatches, and the stylesheet that had stopped reaching the page¶
-
Twenty-two swatches across the style guide: the Okabe-Ito table, the ink and furniture tokens, the achromatic ramp, the RdBu poles and midpoint, and the viridis endpoint. Every number in those sections is recomputable through
contrast(); the hue was not, and the Hue column had been answering it with the word "vermillion". Each swatch restates its hex in an inline--c, so both copies are gated: the source intest_docs_match_code.py, the paint intest_docs_render.py. -
palette.csshad been reaching nothing. Prefixing both scheme rules with:rootwon a specificity fight that did not exist: Zensical setsdata-md-color-schemeon<body>, so:root[data-md-color-scheme="slate"]matches zero elements and the whole stylesheet went dead. The published site fell back to Material's default indigo, with body links at 2.85:1 against a 4.5:1 floor.
It shipped past 44 green tests, and that is the interesting part. They read
hex values out of palette.css and checked the contrast numbers quoted in its
comments, and every one of those assertions was arithmetically true. The
defect was that the stylesheet reached nothing, which arithmetic on two hex
values cannot see. The site is now rendered in Chromium and measured where it
is painted, six pages in both schemes, by the same contrast() that gates the
figures.
-
Two wrapped code spans had become
<h1>headings. Python-Markdown splits blocks before it parses inline spans, so a line beginning with#is a heading even mid-sentence. A hex colour wrapped onto a second line turned the rest of the sentence into a heading, left an unclosed backtick above it, and added a line of prose to the table of contents.--strictdoes not fail on it: nothing is broken, a heading was invented. -
A
<figcaption>link resolved off the site entirely. Paths in raw HTML are resolved against the docs directory and then rewritten relative to the output page, so a../that reads correctly in the source is applied twice. The built page shipped a link tonarenp12.github.io/choosing-a-form/. Every href in the built HTML is now resolved the way a browser does, against the base pathsite_urlpublishes under. -
A bare
filelockimport errored on all four pytest jobs instead of skipping, on the path xdist workers take. The file's promise (skipped, not failed, without the docs-test group) now has a test of its own that runs it in a subprocess with both distributions unimportable.
An audit of the documents the gate arrived with¶
The gate shipped with 122 lines of logic and 13 lines of documentation: one table row, two counts, one comma in a roster sentence, and a figcaption. The audit of that gap found a larger one behind it.
- The README's Threshold column was ungated prose. Four rosters are held to
audit(): the module docstring, the table's first column,SKILL.md's sentence, and the advisory tags. The numbers beside them were held to nothing. Eleven of the twenty rows name a constant and quote its value. All eleven agreed the day the gate was written, which is the argument for the gate:#fcfcfb,#898781and "171 tests" were each right when they were typed too. Every name is now resolved againstcheck_figureandcheck_palette, and a name in neither raises rather than being skipped.
Two of the nine prose rows were checkable numbers wearing prose and were
converted rather than exempted: "40 keys" against figure.mplstyle, and
"Type 42" against the pdf.fonttype/ps.fonttype the sheet declares. The
remaining seven are a literal set, so an unquantified threshold is a decision
someone writes down.
-
The roster size is stated in seven places in the README, and five of them said 19. The gate took the roster to 20 and updated two, leaving "20 passing rows means the figure avoids 20 named defects" reading 19, the sentence that tells a reader what a passing run means. An eighth mention recounts an incident that happened at a particular roster size; its number was removed rather than pinned, because holding history to today's count would make it drift on every new gate.
-
The gallery has seven figures and the README described six, omitting the encoding figure the gate exists for.
gallery.pyand the gallery page had been updated. All three are now held to the number offinish()calls in the script. -
Neither guide had a cyclic colormap, while the gallery shipped a twilight phase portrait.
### Cyclic: twilight, as shippedand### Which kind, and the key it takesare new: the four kinds as four questions, the five constants that decide them, and what each kind costs to get wrong. The kind table is gated againstcmap_kind(), as is the list of maps the guide names as failing. -
"The key follows the kind" lived only in a figcaption, the least discoverable text in the repository. A colorbar is a ruler, so the three continuous kinds take one and categories take a legend; a value outside the measured range is a separate class, drawn in a neutral and keyed off the bar, never as
cmap(0). It is in both guides now. -
Nothing joined a gate to its explanation. The README table says what a gate measures and the reference material says why the rule is there, and the colormap gate is the proof they were unconnected: a table row, a threshold, an advisory tag, four rosters updated, and no explanation anywhere a reader would look, with the suite green throughout.
GUIDANCE_ANCHORSbinds eighteen of the twenty gates to a passage that has to still be there.ClippingandInk coverageare named in an exemption set rather than left silently uncovered. -
The style guide now has a references section. It had none while making the stronger claims;
choosing-a-form.mdhas carried one since it was written. Kovesi (arXiv:1509.03700) for the lightness-monotonicity criterion back-travel measures, Crameri, Shephard & Heron (Nat Commun 11, 5444) for what rainbow and red-green maps cost a reader, Nuñez, Anderton & Renslow (PLoS ONE 13(7), e0199239) for the colour-vision-deficiency floor the Okabe-Ito section rests on, and Moreland (ISVC 2009, 92–103) for the midpoint rule the guide already stated without a source. Each was checked against the publisher. A citation is the one claim in this project that cannot be gated without making the suite depend on the network, and it is worth saying so.
Two ways the suite was green and CI was not¶
main failed CI on every run between the gate landing and this release. Both
causes are invisible on a developer machine, which is how a green local suite
shipped them twice.
-
An author-built colormap is named differently across matplotlib versions.
contour(colors=[...])builds aListedColormapthat 3.8.4, 3.9.4 and 3.10.0 callfrom_listand 3.11.1 callsunnamed. The gate shipped knowing only the 3.11 spelling, so on the two CI jobs running older matplotlib every contour drawn with explicit colours was harvested as a colour encoding, classified qualitative, and hard-failed against all-pairs separation. Three near-black levels are three indistinguishable categories by the letter of that check and one encoding in one hue in fact. Three tests andgallery-field.pngwent with it.ANONYMOUS_CMAP_NAMESholds all three spellings, and a test asks matplotlib what it calls one rather than assuming. -
The test count was unwritable, not wrong.
test_palette_oracle.pyopened with a module-levelpytest.importorskip("cmasher"), which raises during collection: the module contributed zero tests rather than two skipped ones. CI installs pytest, xdist and matplotlib and never the dev group, so it collected two fewer than any machine with cmasher, and the README's test count is compared against whatever the local run collected. No single integer satisfied both. The oracle skips per test now, so collection is the same everywhere. -
The differential had never run in CI at all. The thresholds above were justified by differencing
cmap_kind()againstcmasher.get_cmap_type()across 148 colormaps, and that comparison only ever ran where someone had installed cmasher by hand. One job installs it now. An oracle that runs only where it is remembered is not a check. -
mainis branch-protected: fourteen required status checks, enforced for administrators, and a branch must be up to date before it merges. The gate above was merged into amainthat was already red, and nothing was in the way.
Also¶
plans/is untracked. It held an implementation plan written for an agent to execute and its task queue, and the queue still recorded every task as pending for a gate that had been inmainfor three merges.specs/stays: a design note is the evidence behind a number the code enforces, and the style guide cites one.
Suite: 286 → 482 tests. Gates: 19 → 20.
0.2.0 — 2026-07-28¶
What changed¶
Contour dashfires on any negative level, asked of the strokes the set drew rather than ofnegative_linestyles. It required every level to be non-positive before, which is the one shape a signed field never has.check_mark_ratiomeasures scatter andplotmarkers in one unit. The ratio moves by 4/π.alt_metadata(fig, path)takes an optional path and returns the key that format has, orNonefor the formats that have none. Called without a path it returnsDescription, as every earlier version did.ADVISORY_GATESadded as the one list.OverplottingandContour dashare advisory and were documented as able to fail.- A docs site, published to GitHub Pages from
.github/workflows/docs.yml. Every page except the gallery is a symlink to the file that already existed. - Dark mode takes sky
#56B4E9for body links; light mode keeps Okabe-Ito blue#0072B2. - Muted ink changed
#898781→#777570in the guide's table, matching whatfigure.mplstyleships. The old spelling stays inINK_TOKENS. - Corrected: "only the first four slots clear all-pairs" is five; full-range
viridis is 1.26:1 on white, not 1.23:1 on the retired
#fcfcfb; the grayscale separations are relative luminance, not ΔL;SKILL.md's roster listed eighteen of nineteen gates;demo.png's site alt text was a paraphrase. _halono longer returns "no casing" when matplotlib's private_gcmoves.- Smaller:
--venuesruns without matplotlib; the dual-axis message says "two data scales";ordinal()no longer divides by zero atn=1. - Suite: 224 → 268 → 286 tests.
Why it changed¶
A minor release rather than a patch, because the gates now answer differently.
Nothing here is a redefinition — every change is a fix to code that was not
measuring what it said — but a figure that passed on 0.1.4 can fail on this
one, and that is the fact a version number is for. Two of the nineteen rows
changed verdict: Contour dash can fire on signed data, which is the only
shape it never fired on, and Mark ratio compares scatter against plot
markers in one unit rather than two, moving the ratio by 4/π. alt_metadata
takes an optional path and keeps its old behaviour without one.
The three sections below are three audits — the gates, the documentation site, then the documents themselves — run in that order, each finding the same species of defect one level further out.
An audit of the gates, and what it found¶
Two of the nineteen rows were not measuring what they claimed, and four documented numbers were not the numbers the code computes. All six are the same species — a claim nobody had run — which is what the rest of this file is about, so each fix ships with the executable link that keeps it true.
- The contour-dash gate never fired on signed data. It required every
level to be non-positive, which is the one shape a genuinely signed field
never has:
contourover data spanning zero draws levels either side, and matplotlib dashes the negative half. Asin(x)cos(y)field shipped four dashed isolines and the gate reported "no auto-dashed negative contours". The only test it had drew-(x² + y²), non-positive throughout — the one shape that met the condition — so the hole was invisible from inside the suite.
The rule is now "any negative level", and it is asked of the strokes the set
actually drew rather than of negative_linestyles, which is what the gate
should have read from the start. Six tests cover it: the signed field, the
signed field drawn solid, all-negative both ways, all-positive, colormapped,
and filled.
-
Two rows were documented as able to fail, and cannot.
OverplottingandContour dashreturn onlyTrueor"warn", but the README table gave both a "Fails when" and the prose counted five advisory rows against an actual seven.ADVISORY_GATESincheck_figure.pyis now the one list; the table's tags, the count in the prose, and the claim that none of those functions has a returning-Falsepath are all tested against it. -
check_mark_ratiomeasured two mark kinds in different units. Scattersis an area in pt²;markersizeis a diameter, and squaring it gives the bounding square rather than the disc — 4/π = 1.27× too large. On a figure drawing one kind the bias cancels in the ratio and nothing shows. On one mixingscatterwithplot(marker=...), two marks of identical drawn area reported 1.3×, which against a 5.0 threshold fails a legal figure at a true 3.9× and passes a bad one at 6.4×. -
alt_metadatawarned on every PDF save, and crashed on every jpeg. The documented call — the one inSKILL.md, in the README and in both examples — issavefig(path, metadata=alt_metadata(fig)), and what each format does with that turned out to be four different things, three of them undocumented:
| Format | Description |
Subject |
|---|---|---|
| png | lands in a tEXt chunk | lands |
| warns, info dictionary is closed (PDF 1.7 §14.3.3) | lands | |
| svg / svgz | lands in Dublin Core | raises |
| ps / eps | accepted, carried nowhere | carried nowhere |
| jpg, webp, tif, raw, pgf | raises | raises |
So the key cannot be one value, and for the bottom row it cannot be a value at
all: matplotlib's guard is elif metadata is not None: raise, which rejects
{} exactly as hard as a full dict. savefig(path, metadata={}) on a jpeg
was already a traceback before any of this — a figure with no description
attached hit it too.
alt_metadata(fig, path) now reads the suffix and returns the key that
format has, or None — savefig's own default for the argument — for the
ones that have none. Called without a path, or with a buffer whose format
cannot be read, it returns Description as every earlier version did. An open
file is asked for its name. The table is not written from memory: the suite
saves a real figure in every format it names and asserts no warning and the
text present in the bytes, and saves in every format it excludes and asserts
the call survives.
-
The guide's ink table credited the sheet with a token it does not ship. Muted ink was listed as
#898781, whichfigure.mplstylestopped setting whencheck_text_readabilityfailed the sheet's own tick labels against it at 3.59:1 — under the 4.5:1 a glyph stem needs. It is#777570. The old spelling stays inINK_TOKENSso figures built on the old sheet still read it as furniture. Every hex the table credits to the sheet is now resolved against the sheet throughrc_params_from_file, so the table cannot quote a value the sheet does not define. Third instance of this exact failure, after the contrast column and the retired#fcfcfbsurface. -
"Only the first four slots clear all-pairs" was off by one. Five clear it, at ΔE 11.2 under deuteranopia against a target of 8; six is the first count that fails, at 7.9 (
#009E73vs#CC79A7). Four was a number nobody had run, stated in three documents and the appendix constant as though it were a measurement. The limit is now derived in the suite by askingcheck_palette.check(..., all_pairs=True)for the largest passing count, and the prose and the constant are held to it. -
_haloreads a matplotlib internal and failed silently.Strokekeeps its kwargs in a private_gcand there is no public accessor; the fallback returned "no casing", which would have meant every cased label in every figure being judged against the raw backdrop the casing exists to survive — correct work failing, with nothing saying why. It now tries any other dict attribute carrying aforeground, and a direct test makes an upstream rename a red suite rather than a quiet regression. -
Smaller, same shape:
--venuesno longer requires matplotlib to print a table of numbers; the dual-axis message says "two data scales" rather than "two y scales", sincetwinylands there on the same argument; the appendix'sordinal()no longer divides by zero atn=1; and the scipy-optional test now compares the KD-tree and numpy nearest-neighbour paths against each other on a figure that actually has a scatter — the old one audited a figure with none, proving the import was soft but never that the fallback computes the same thing.
Suite: 224 → 268 tests.
Docs site¶
Documentation only. No code, no thresholds, no packaging change — the wheel built from this commit is byte-identical in what it ships.
- A docs site, Zensical, published to GitHub Pages
from
.github/workflows/docs.yml. It exists becausestyle-guide.mdis a long reference document whose only affordance on GitHub was scrolling, and the thing people do with it is look one threshold up.
Every page except the gallery is a symlink to the file that already
existed. That is not tidiness: test_docs_match_code.py reads
skill/references/style-guide.md and asserts its contrast table against
contrast(), and it can only keep doing that if the page the site serves is
that file. A docs/ of hand-maintained copies would pass the entire suite
while publishing numbers that had drifted — the failure that file already
exists to prevent, one level further out. test_docs_site.py asserts no page
has quietly become a copy.
- The theme's two link colors are a measurement, not a preference. Okabe-Ito
blue
#0072B2is 5.19:1 on white but 3.10:1 and 3.77:1 on the two dark backgrounds Zensical ships (classicathsl(225, 15%, 14%)=#1e2129,modernathsl(225, 15%, 5%)=#0b0c0f— both blue-tinted, neither neutral). Body-text links need WCAG's 4.5:1, not the 3:1 floor series colors are held to, so dark mode takes sky#56B4E9at 6.98:1 and 8.48:1 instead. One hue for both would have shipped a site about colorblind-safe figures whose own dark-mode links miss the floor. Every number is recomputed by the test suite against a background derived from HSL rather than pasted, for the same reason every other quoted number here is executable.
Both variants are measured, not just the configured one. variant is a
one-line edit, and a measurement that is true until someone flips a line is
the failure this project is about.
- Strictness is a flag, and it does less than its name suggests. The docs
build runs on pull requests as
zensical build --strict, which fails on a broken link between pages. It does not fail on a nav entry whose file cannot be read: that page is silently not built, the sidebar renders a raw./style-guide.mdhref, and the build exits 0. Measured, not assumed — every page here is a symlink, so that is the failure most likely to happen.
Three checks rather than one, then. The symlink check runs before the build
and is the only thing that catches a dangling pointer; --strict covers
links between pages; and a post-build check asserts every page named in the
nav produced HTML. test_docs_site.py carries the first as a unit test, so a
file moved under skill/ fails pytest and not only CI.
Zensical also reads a leftover mkdocs.yml and silently ignores its
strict: true — the first build of this site was exactly that config — so a
test asserts there is no mkdocs.yml in the repository.
Zensical is 0.0.x, so the docs dependency is pinned >=0.0.51,<0.1 rather
than floored. Nothing else in the project depends on it; the checkers are not
involved in building the site.
-
The README claimed five defects;
examples/gallery.pyenumerates six. Both numbers were prose, so neither could be wrong loudly, and the wrong one was old enough to get copied into the docs site while it was being written — a number in prose spreading rather than being corrected. Fixed to six, andtest_docs_match_code.pynow asserts the three places that state the count agree with each other. -
The palette sections now paint the hue beside the hex. Twenty-two swatches: the Okabe-Ito table, the ink/furniture table, the achromatic backdrop ramp, the
RdBupoles and midpoint, and the viridis endpoint. Every other cell in those tables is recomputable — a contrast ratio goes back throughcontrast()— and the hue is not. The Hue column had been answering it with the word "vermillion".
Each one is ::before on the code span holding the hex, written as an
attr_list attribute list, and it restates that hex in an inline --c. The
first version was a sibling <span>, which put a soft wrap opportunity
between the square and the value it labels: the diverging poles wrapped, and
the page shipped a red square at the end of one line with #b1182b at the
start of the next. Generated content cannot be orphaned from the element that
generates it.
The restated hex is gated at both ends. test_docs_match_code.py reads the
source and asserts the declared color is the hex the code span spells out, and
that no palette row is missing a swatch. test_docs_render.py renders the
page in both schemes and asserts the browser paints the hex the reader can
see — compared against the code span's text, not against the inline style,
which is the copy under test. It also asserts area and a frame: a ::before
with no box paints the right color over no pixels, and #ffffff is the
surface row of the ink table, so on the light page the frame is the entire
difference between a swatch and nothing at all.
Neither end is sufficient alone. A source check cannot see a stylesheet that
reaches nothing, which this site shipped for a release; a browser cannot see a
square confidently painted the wrong color in both copies at once. Both first
drafts here failed to their own species of that: the size test floored at "not
zero", which a collapsed swatch clears on 4px of border, and dark mode drew
its white mat in border rather than box-shadow, taking a third of the hue
with it and turning slot 1 from black into an outline. The mat is there
because the column beside it is headed "Contrast #ffffff". Orange at 2.25:1
looks emphatic on a near-black page; the mat is the surface that number is
about.
An audit of the documentation, and what it found¶
Every number, roster and code sample in the published documents, read against the code that produces it. Five drifts, all the same species as the ones above, and each now has the executable link it was missing.
-
The style guide still taught the
alt_metadatacall this release fixes.savefig(path, metadata=alt_metadata(fig))— the form that warns on every PDF save and that SVG rejects.SKILL.mdand both examples were corrected when the fix landed;style-guide.mdwas not, so the release note announcing the fix would have shipped beside a document still teaching the break. Every document that teaches the call is now checked for the pathless form. The CHANGELOG is excluded, because it quotes the broken call deliberately. -
SKILL.md's prose roster listed eighteen of the nineteen gates, omittingContour dash, from the commit that added that gate until this one. This is the fourth roster of the same list, and the only one nothing read — the README table and the module docstring have been checked againstauditfor two releases. Prose does not use the gate's own label, so the join is written down as a map, and the map is asserted complete againstaudit: a twentieth gate cannot be added to the code and to two rosters while quietly skipping this one. Order is checked too, and the roster now runs in the orderauditdoes. -
Full-range viridis was quoted at 1.23:1, which is its ratio on
#fcfcfb— the surface retired three releases ago. On white, which is whatfigure.mplstylerenders, it is 1.26:1. Fourth instance of the retired-surface bug, and the reason the existing guard for it cannot only be a grep for the string: this ratio was in a sentence, not in the table the row-by-row check reads. Both documents now have the hex checked against where viridis actually ends and the ratio againstcontrast(). -
The grayscale separations were labelled ΔL and are not.
ΔL 0.011andΔL 0.264are WCAG relative luminance, which is the right channel for a question about desaturation and the wrong label in a document that states OKLab ΔE ×100 as its unit. In OKLab the same pairs are 0.018 and 0.221 — the ordering survives, the numbers do not, and a reader who recomputes concludes the guide has drifted. Nothing was wrong except the unit, which is enough. Both documents now name the unit and both pairs carry their hexes, so all four numbers are checked againstrelative_luminance(); the aside giving the OKLab equivalents is checked againstlinear_to_oklab(), because it is two more numbers in prose and this file is about not shipping those. -
demo.png's alt text on the site was not the string the figure carries.docs/gallery.mdstates outright that every alt text on the page is what was passed todescribe(fig, ...), which is what makes the page's alt text checked rather than written once and forgotten. True of the six gallery figures — exactly, verified — and false of the demo, whose alt had been paraphrased in the README and copied into the site from there. A claim that the documentation is generated from the code, written in prose, about documentation that was not. The seven alt texts are now asserted to be exactly the seven descriptions the examples attach.
Every gate added here was run against the defect it was written for: the drift
reintroduced, the gate confirmed red, the file restored. The CHANGELOG entry for
the docs site also claimed style-guide.md was 367 lines when it was 386 — that
number is gone rather than corrected, since it would drift again the next time
the guide grows.
Suite: 268 → 286 tests.
0.1.4 — 2026-07-28¶
One dead gate on the install path, and the missing way to point a live one at your own sheet. Nothing about the thresholds changed.
What changed¶
-
The wheel ships
figure.mplstyle. It ships besidecheck_figure.py, which is the first location_style_sheetprobes. Through 0.1.3 the wheel carriedskill/scriptsand nothing else, so onuv add figure-gatethere was no sheet anywhere the checker looks: the style-sheet row read "no figure.mplstyle beside this script, nothing to compare" and returned a pass — for a figure drawn on stock matplotlib withplt.style.useforgotten entirely, which is the first failure the check's own docstring names. The gate is advisory, so nothing was wrongly certified composed; it simply did nothing on the path the README advertises. No code changed, only the build config. -
STYLE_SHEETis a module-level constant. The sheet is meant to be edited per document, so a project whose sheet lives somewhere other than beside the checker needs a way to say so, and until now that way was patching a private function.Nonekeeps the existing behaviour: beside the script, thenassets/next to it. A path that is set and does not exist reports a warn naming it, rather than falling back to a sheet the project did not ask for. -
The install path is tested, and tested twice over.
tests/builds the layout the wheel produces and runs the checker inside it, with the checkout'sassets/off the import path — the copy-based tests could never have caught this, because from a checkout the sheet is always one directory up. And CI now builds the real wheel, installs it, and asserts the gate fires on a stock figure and clears once the shipped sheet is applied; a mapping inpyproject.tomlis not evidence about what the build emits. -
The README's test count is checked against pytest. It was wrong at 0.1.2 and hand-corrected at 0.1.3, which is the same fix twice. A test now reads the number out of the README and compares it to a fresh collection, so the next drift fails rather than ships. The count is 178.
0.1.3 — 2026-07-28¶
Mostly the README. 0.1.2's fix shipped without the project page explaining the condition it fixed, and PyPI renders the README from the released sdist, so the explanation could not reach the project page without a release of its own.
What changed¶
-
The README documents the HiDPI behaviour, in a section under "Use it": what a Retina or scaled-display backend does to
fig.dpi, both ways that went wrong through 0.1.1, and the one consequence a user can trip over — an audited figure is no longer attached to its GUI canvas and will not show in a window. It also names the reason the bug survived: every test and example here pins Agg, so nothing in CI could construct the failing condition. -
OVERPLOT_THRESHOLDis a module-level constant. The README's opening claim is that every threshold is one you can read and change, and this one was a local insidecheck_overplotting— cited in the gate table by a name that could not be imported. The value is unchanged at 0.5. -
Two README claims corrected against the code. The test count said 166 and the suite is 171. And
check()returns(rows, ok)whileaudit()returns(ok, rows); the opening paragraph said check "does the same", which reads as a promise about the tuple order that the code does not keep. The order is now stated. Neither function changed — unpacking is published API.
0.1.2 — 2026-07-28¶
What changed¶
- The audit no longer depends on the display it ran on. A HiDPI GUI backend
— macosx on a Retina display, Qt on a scaled desktop — sets
fig.dpito the authored dpi times the display's device pixel ratio when the figure is created, and_rendererkept that canvas whenever it could measure text. So the checker ran at 2× on exactly the machines figures get authored on.
Two things went wrong at once. Text window extents come back in physical
pixels while canvas.get_width_height() reports logical ones, so
check_clipping compared 2× coordinates against a 1× bound and called every
label past the midpoint clipped — a full-width figure with tick labels failed
a gate it should pass, which is the wrong direction for a gate to be wrong in.
And every threshold calibrated in pixels — TEXT_EDGE_WINDOW = 9, measured
against a 1.6pt hairline at 150 dpi — covered half the distance it was
calibrated for. Ink coverage read 0.05 under macosx and 0.04 under Agg on the
same figure.
_renderer now resets fig.dpi to the authored value and builds the Agg
canvas unconditionally, so a figure's verdict is a property of the figure.
One consequence worth knowing: an audited figure is no longer attached to its
GUI canvas and will not show in a window. check_ink and
check_text_readability already rebound fig.canvas; it is now unconditional.
-
The tests can see this class of bug now. They could not before, because
conftestpins Agg and so does every script inexamples/— which is why a real bug sat behind a green suite and a green CI. The new tests simulate a HiDPI canvas instead of requiring a display, and one of them asserts every audit row is identical at 1× and 2×, messages included. -
The README gate roster is being read again. The 0.1.1 README rewrite added a Threshold column to the
check_figure.pytable, and the test that checks that table against whataudit()returns matched rows by shape. It matched nothing, and compared an empty list against 19 gates. It now reads the first cell whatever the column count, and asserts it read something at all — the guard the contrast table has had all along.
0.1.1 — 2026-07-27¶
What changed¶
- Releases are signed. 0.1.0 went out through
uv publish, which despite offering--no-attestationsuploaded no provenance at all — PyPI's integrity endpoint 404s for both of its files. The upload now runs through the PyPA action, which attaches a PEP 740 attestation. 0.1.0 cannot be fixed; published files are immutable. - The TestPyPI rehearsal uploads the same way the real release does. It did not before, which is why the missing attestations survived a rehearsal.
0.1.0 — 2026-07-27¶
First release on PyPI. Everything below is the work that preceded it.
What changed¶
- Seven new gates:
check_text_readability,check_line_weight,check_fonts,check_series_color,check_dual_axis,check_form,check_identity_channel,check_style_sheet,check_label_attribution,check_overplottingandcheck_contour_dash. figure.mplstylesetsaxes.prop_cycleto the six Okabe-Ito series slots, andpdf.fonttype: 42/ps.fonttype: 42. Yellow and black are held out.xtick.color/ytick.colorchanged#898781→#777570, 3.59:1 to 4.6:1 on white.audit(fig, venue=...)added for twelve known venues, withpython check_figure.py --venueslisting them.CONTENT_WIDTH_PTstill wins for anything not in the table.describe(fig, ...),alt_metadata(fig)andcheck_alt_textadded, advisory.audit(fig, context_axes=[ax])added: a filled backdrop is a context surface rather than data ink.check_palette.pylearns--ink, exempting listed hexes from the chroma-floor and lightness-band rows.- scipy is optional, a
fastextra.uniform_filteris replaced by a numpy box blur,KDTreeis gone from label attribution, andcheck_overplottingfalls back to an O(n²) numpy path. - Series color is scoped per panel. One series drawn several ways is one identity. Label attribution ignores legend entries.
- Polar radial tick labels are exempt from
check_text_readability, and the row reports how many went unjudged. check_redundancyskips axes withaxisonfalse and counts only visible tick labels.check_inkdecides emptiness structurally rather than by pixel fraction.examples/gallery.pyadded: six figures, each audited, with CI failing if any figure fails.skill/references/choosing-a-form.mdadded, plus a step inSKILL.md.- Decided and written down: identity does not ride on label colour, and a
legend entry is not a direct label.
examples/demo.pylabels its curves directly, with cartographic casing.
Why it changed¶
Four gates that were measuring the wrong thing¶
Found by running the checker over ordinary matplotlib figures nobody built for it — the corpus check CONTRIBUTING asks for, applied to the checker itself rather than to a new gate.
-
Polar radial tick labels are no longer judged by
check_text_readability. Every ordinary polar plot failed. matplotlib places radial labels inside the disc andset_rlabel_positiononly moves them to another angle, so "move the label to clear ground" named a move that does not exist. The first fix exempted only the clutter clause and was not enough: the contrast clause went on failing eight of eight polar plots built on this project's ownfigure.mplstyle, at 2.0:1 against a curve the radial axis crosses by construction. A gate the bundled sheet cannot satisfy is measuring the projection, not the figure. Both clauses now skip these labels and the row reports how many went unjudged, so the author is told rather than left to assume they passed. Author-placed text on a polar axes is still judged. -
check_redundancyno longer reads furniture that never renders. Threeimshowpanels ataxis("off")were told to "use sharex/sharey" on the strength of the tickTextobjects matplotlib keeps for an axis it is not drawing. Axes withaxisonfalse are skipped, and the tick clause now counts only visible labels. -
check_inkcan see an empty panel again. The README has always claimed the row catches "a panel is empty", and the pixel fraction could not: a blank axes measures about 0.03 from its frame and ticks alone, over the 0.02 floor. The blank subplot in a grid — the case that actually ships in papers — read as merely sparse. Emptiness is now structural: was anything drawn into this axes. The fraction clause is unchanged and still governs sparse and saturated panels. -
check_line_weighthas tests. It shipped with none, which is the one thing CONTRIBUTING says a gate may not do. Four now: a hairline fails, a legal stroke passes, a 1.2pt stroke fails once placement thins it to 0.6pt on the page, and the grid is not held to the data floor. The gate was correct — it had simply never been watched work.
Text readability — the gate the demo needed¶
check_text_readabilitymeasures whether each string can be read where it sits. Two clauses, both off rendered pixels. Clutter: the figure is drawn a second time with every string hidden, and that render is the backdrop each label was placed onto; pixels inside a label's box that no blend of {its surface, the grid, the axis rule} explains are data ink passing through the text. Contrast: the text against the backdrop it actually got, at the WCAG text threshold (4.5:1, or 3:1 large) rather than the 3:1 a mark gets, because a glyph stem is thinner than a mark.- Measuring the backdrop rather than the finished render is the point. Casing hides the evidence: a white halo over an orange curve renders as clean white while punching a visible gap through the data. Both halves of that are defects and this reads them as one number.
- Clutter is an edge, not a deviation from the dominant color. The first version tested each pixel against the box's modal color and failed every annotation ever placed on a heatmap, because a smooth ramp differs from its own mode everywhere while being, to a reader, one surface. Now each pixel is tested against a local average of its neighbours, so a viridis field is ground and a hairline is a mark.
- It found the sheet's own ticks.
xtick.color/ytick.colorshipped at898781, which is 3.59:1 on white — under the text threshold on every figure in the repo. Now777570at 4.6:1, still below the 7.94:1 axis label, so the hierarchy axis label > tick label > grid survives. examples/demo.pywas the first thing it failed. All three direct labels sat on their own curves —'Baseline'on data ink over 17% of its box — whilecheck_label_attributionpassed them, correctly, because a label printed on its own line is attributed perfectly. The cause was alignment:ha="center"clears a sloped curve at the anchor and puts both ends of the box back down on the line. Fixed by aligning toward the side the curve is leaving, and by anchoring on the extreme of the noise across the label's own span rather than on one point.
Research-standard gates¶
check_line_weight: 1pt on the page, per SIAM's instructions for authors ("lines one point or thicker; thinner lines may break up or disappear"). Measured throughpage_scalelike the type floor, since it is the same failure. Gridlines are held to a lower floor than data on purpose.check_fonts: Type 42 embedding, and the face you named. matplotlib defaultspdf.fonttype/ps.fonttypeto 3; IEEE PDF eXpress rejects the upload and ACM/Elsevier reject the submission, with nothing warning you because the figure renders identically. Also warns when none of the faces infont.<family>is installed and matplotlib has silently substituted its own. Advisory, because it reads global rcParams rather than anything the figure carries — the hard gate is on the shipped sheet, in the test suite.figure.mplstylenow setspdf.fonttype: 42andps.fonttype: 42.
Venue content widths¶
audit(fig, venue="neurips")replaces hand-measuringCONTENT_WIDTH_PTfor twelve known venues (NeurIPS, ICLR, ICML, ACL, IEEE, Nature, LaTeXarticle, and the column widths of the two-column ones).python check_figure.py --venueslists them.CONTENT_WIDTH_PTstill works and still wins for anything not in the table.
Alt text¶
describe(fig, ...)/alt_metadata(fig)/check_alt_text. Across 100,000 public Jupyter notebooks, 99.81% of programmatically generated images shipped with no alt text, nearly all matplotlib.alt_metadataproduces themetadata=dict forsavefig, so the description survives into the PNG, PDF or SVG. Advisory: on a paper the description frequently is the caption, and the caption lives where this cannot see it.
check_label_attribution was passing nearly everything¶
- Fixed a regression that had disabled the gate in its common case. The
comparison distance had been changed from "the minimum over every other curve"
to a KD-tree query for the k nearest pooled points. For a label sitting near
its own dense curve, every one of those points belongs to that curve, no other
curve is ever reached, and
d_otherstays infinite — so the gate passed every label whose own curve was nearest, which is nearly all of them. Back to the explicit minimum, with a regression test for a label in the corridor between two curves. - It found a real defect the moment it worked.
gallery-convergence.pnghad its direct labels past the right-hand end of each curve, 29px from their own and 35px from a neighbour's: a label outside the data is not resolved by proximity to anything. Moved to the left of the panel where the log-log fan is three decades wide.
No hard scipy dependency¶
- The README promises three files and no install, and a hard
scipyimport had quietly broken it.scipy.ndimage.uniform_filteris replaced by a separable cumulative-sum box blur in numpy;scipy.spatial.KDTreeis gone from label attribution entirely;check_overplottingusescKDTreewhen it is importable and an O(n²) numpy path when it is not. scipy is now an optionalfastextra. Tested with the import forced to fail.
examples/gallery.py — six harder figures¶
- Small multiples on shared scales; a filled field with isolines and a colorbar;
an axis-free schematic; the three forms
choosing-a-form.mdargues for; a log-log convergence plot with a slope triangle; a dense orbit diagram. Each is audited, and CI fails if any figure fails. - Writing them found six defects in the checks themselves, which is what they are for:
- the readability gate reported a schematic's tick labels, which
ax.axis("off")means never reach the page — it now skips_ghost_ticksthe waycheck_clippingalready did; check_inkmeasured colorbar axes, which are a solid ramp by construction, so every figure with a colorbar stood at WARN for the one axes in it whose density nobody chose;check_line_weightmeasured a colorbar's own 0.4pt dividers;_artist_kindcalledplot(..., linestyle="none", marker="o")a line, so a path and its own start marker in one hue read as a wrapped color cycle;- the clutter metric failed every heatmap annotation, as above;
check_label_attributionwas passing nearly everything, as above.- And two defects in the figures that no gate caught, which is what step 7
of the procedure is for: the schematic's feedback loop ran off the bottom of
the canvas (
connectionstyle="bar"drops by a fraction of the span, so a wide loop went fifteen units below an axes that stops at zero), and the convergence plot's slope triangle sat in the only corner its direct labels could use. Both were obvious in the PNG and invisible to every check.
Overplotting / mark-density WARN¶
check_overplottingdetects scatter marks that merge into a blob. For each scatter (PathCollectionwith offsets), estimates the fraction of points whose nearest neighbour in display pixels is within one marker radius — points that visually overlap. Above ~50% overlap the WARN fires: reduce counts, use hollow markers, add transparency, or switch to hexbin. The 0.5 threshold keeps the entire existing corpus clean (all well-separated scatters pass). A WARN, not a FAIL — dense marks are legitimate for some forms (e.g. a swarm plot).
Context-surface ink stops a standing WARN¶
- Ink coverage accepts
context_axes. A filled contourf backdrop (loss landscape, terrain) saturated 100% of the axes pixels, triggering a standing ink WARN on every such figure — the "advisory everyone learns to ignore." Newaudit(fig, context_axes=[ax])declaration tells the checker the fill is a context surface, not data-ink. The pixel buffer is split into two clusters via 2-means on color; the larger cluster (the surface) is subtracted from the ink count, so only marks on top of the backdrop are measured. A terrain panel with a few sparse marks now PASSes instead of WARNing. Existing heatmap behavior is unchanged (nocontext_axes→ same as before).
Two false-signal fixes, no new gates¶
- Contour dash warns on auto-dashed negative levels. A monochrome contour
with all-negative Z ships dashed isolines via matplotlib default
(
contour.negative_linestyle). The skill's own convention is dashing = unobserved / projected / threshold, so this is a silent semantic error no existing gate saw. Newcheck_contour_dashwarns; passlinestyles="solid"on signed data. Style guide note added. check_palette.pylearns--ink. Ink/neutral hexes were flagged by the chroma-floor and lightness-band rows, but an ink token is not a series hue. New--ink "#52514e,#898781"flag exempts listed hexes from those checks while keeping them in CVD/normal separation and contrast-vs-surface coverage. Mirrorscheck_figure'sINK_TOKENS.
The series-color and label gates learn the figure's structure¶
The new gates above read a flat bag of hues and text, and a bag throws away the structure the author encoded — which panel a hue lives in, what kind of artist drew it, whether a piece of text is a direct label or a legend key. Four figures that were mechanically correct got failed for it. Each fix gives the harvester back one piece of that structure.
- Series color is scoped per panel. The comparison, the hue count and the adjacent-versus-all-pairs mode are now asked of one axes at a time. A figure-wide harvest gated hues that never share a frame — a flow-chart node in one panel measured against a regression curve in another — and let a single scatter flip every line-only panel into the stricter all-pairs regime. The panel is the unit a reader separates hues within.
- One series drawn several ways is one identity. The wrap check — one hue, two labels — is narrowed to labels on artists of the same kind. A cycler that wraps reuses one artist type; a posterior shown as a credible band, its mean line and its observed points is three kinds in one hue, one series shown three ways. Two lines in one hue with two labels is still the wrap it always caught.
- Label attribution ignores legend entries. A legend is a lookup key placed
away from the curves by design, so judging its entries by proximity to those
curves could only ever fail. They slipped the
t.axes is axguard because a legend child's.axesis the parent axes; they are now dropped explicitly. - Ordinal ramps on marks belong in a colormap (guidance). A ramp is built to
violate the categorical floor, and a
scatter(c=[rgba, …])list reads as that many independent hues. The style guide now says to draw itscatter(c=values, cmap=ListedColormap(ramp)), which the harvester already exempts as a value encoding — the intent lands in the code instead of a flat bag of hues.
Five new gates, and the two scripts finally speak¶
The motivating failure, reproduced end to end: a figure drawn on matplotlib's
default tab10 cycle with a twinx second y axis passed every check in
check_figure.py and printed -> COMPOSED. The same three hues through
check_palette.py reported
CVD separation (adjacent) worst #ff7f0e vs #2ca02c dE 1.4 (protan) — one hue
to a protanopic reader. Two scripts in one project, and nothing connected them.
figure.mplstylesetsaxes.prop_cycleto the six Okabe-Ito series slots, in canonical order. Until now the sheet set every visual default except the one that decides whether a colorblind reader can separate two curves, so a figure built on it inheritedtab10. Yellow and black stay held out — yellow at 1.32:1 vanishes as a hairline, black is the ink token.- Series color reads the hues off the figure's own artists and puts them through the palette gates, inferring adjacent-versus-all-pairs from whether the marks are scatter. Also fails a seventh distinct hue, and one hue carrying two labelled identities — which is what the cycler wrapping looks like, and was prose only before. Harvest excludes colormapped artists and the sheet's ink tokens; the lightness-band and chroma rows are deliberately not applied, because a gray control curve is legal.
- Dual axis fails two axes sharing a frame when both carry data: the crossing
point of the curves is then set by the limits rather than the data. A bare unit
relabel —
secondary_yaxiswith no artists of its own — still passes. - Form fails the mechanical subset of form choice: pie/donut, 3D axes, and bars on a truncated baseline. Log-scale bars are exempt, since a log axis cannot contain zero.
- Identity channel warns when two or more labelled hues carry identity with no legend and no in-axes text. A warning rather than a gate: the script cannot tell a direct label from any other annotation, and guessing would fire on correct work.
- Style sheet warns when the keys in
figure.mplstyleare not the ones in effect. Catches the#-is-a-comment trap, a forgottenplt.style.use, and a later rcParams override in one row. - Label attribution fails a direct label that is not plainly nearest the
curve it names.
Text collisioncompares text against text, so a label alone in the corridor between two curves clears it; text against data is a different question and nothing was asking it. Measured in display space as a ratio — the reader's judgement is comparative, not a distance in points — and harvested only from text matching exactly one series label, because a callout or a panel letter attributes nothing to a curve.
Decided: identity does not ride on label color¶
The usual advice is to color a direct label to match its series. Measured on
this palette, against this project's own thresholds, it cannot be done: text
needs 4.5:1 to be legible, and darkening the Okabe-Ito hues that far puts orange
at dE 18.6 from its own line and sky blue at 17.1 — both past the NORMAL_FLOOR
of 15 at which check_palette calls two colors different series. The label
would read as a fourth hue. Below 15 the text is not legible. No setting
satisfies both, so labels stay ink black and identity rides on proximity, which
Label attribution now gates rather than assumes.
examples/demo.py gains cartographic casing on its labels — a surface-colored
stroke under the glyphs — so a gridline crossing behind a label stops breaking
its edges.
Decided: a legend entry is not a direct label¶
The guide required a "visible direct label" for a sub-3:1 hue and examples/demo.py
used a legend, so one of the two was wrong. Settled the strict way, because the
obligation follows from the measurement: a faint mark plus a legend leaves the
reader matching a small faint swatch to a small faint curve, which is the step a
direct label removes. The demo now labels its curves directly.
New reference¶
skill/references/choosing-a-form.md, plus a step in SKILL.md's procedure.
Grounded in statistical graphics rather than general information design —
Cleveland & McGill's ordering of the elementary perceptual tasks, and the
statistical results behind the rules that matter most in teaching material: what a
box plot hides at small n, why a cut baseline misstates every ratio, why two bars
are the wrong form for paired data, and why overlapping confidence intervals are
not a significance test.
Earlier in Unreleased¶
Corrections, no new gates. Nothing that passed before fails now.
What changed¶
- Surface is white everywhere.
check_palette.pydefaulted to#fcfcfb, a surfacefigure.mplstylenever rendered, so every contrast ratio in the style guide was measured against a page that did not exist. Reddish purple was listed as needing a mandatory direct label at 2.98:1; against the surface actually used it clears 3:1 at 3.06. Table recomputed,--surfacestill available for a genuinely tinted page. tests/test_docs_match_code.pyparses the guide's contrast table and checks every quoted number, and every † marker, againstcontrast(). The drift above is now a test failure rather than something noticed in a year.placed_fraconaudit()/report(). A figure placed at0.48\textwidthwas measured as if it were full width and certified at twice the type size it shipped at. Passingplaced_fracwithoutCONTENT_WIDTH_PTraises rather than silently assuming 1.0.- Mark ratio sees line markers. It read only
ax.collections, somarkersize=3besidemarkersize=30passed clean. Bars stay excluded on purpose — a bar 30× another bar is the encoding working, and the docstring now says so instead of leaving it to look like an oversight. figure.mplstylecarries the mark and output defaults:lines.linewidth,lines.markersize,axes.linewidth,patch.linewidth,legend.handlelength,errorbar.capsize,axes.axisbelow, plusfigure.dpi,savefig.dpi,savefig.bbox,savefig.facecolor. These were prose passed by hand at each call site; at matplotlib's default 100 dpi the "render a PNG and look at it" step produced a PNG too soft to show the defects it was opened to find.bbox_inches="tight"documented as a trap beside the#-is-a-comment one, and pinned in the sheet. It trims to drawn content, so the saved width stops being the authored width the type gate derives its floor from — the gate then certifies a size the shipped file does not have.axes.titlesize/titleweightannotated as panel-title settings, resolving a contradiction with the guide's ban on in-figure titles.
0.1.0 — 2026-07-22¶
First release.
What changed¶
check_palette.py— lightness band, chroma floor, CVD separation (protanopia and deuteranopia, OKLab ΔE), normal-vision separation, contrast against the surface, and a four-gate mode for ordered ramps. Standard library only.check_figure.py— clipping, text collision, alpha stacking, mark ratio, axis redundancy, type size on the printed page, and ink coverage, read off a built matplotlib figure's own artists.figure.mplstyle— typeface, ink, type sizes, spines, grid, frameless legends.skill/— Agent Skill wrapper (SKILL.mdplus the full style guide).- 49 tests, including per-gate failure cases and a guard against the style sheet's colors silently not applying.