Skip to content

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 (default math.inf), VENUE_TYPE_CEILING_PT (nature, nature-column: 7.0), VENUE_PANEL_LABEL_PT (nature, nature-column: 8.0) and type_ceiling_pt(venue=None, *, panel_label=False), the stricter of TYPE_CEILING_PT and the venue's row.
  • load_config: venue selects the venue type_ceiling_pt() reads; a later file setting venue or CONTENT_WIDTH_PT replaces 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.5 joins the dev group.
  • test_a_tritan_gate_at_cvd_target_would_fail_okabe_ito in tests/test_palette.py.
  • EXTERNAL_CLAIMS["cividis optimisation"], and three RETRACTED_CLAIMS entries, in tests/test_prose_claims.py.
  • EXTERNAL_CLAIMS["vislint_mpl linting built figures"] and RETRACTED_CLAIMS["no other tool reading the built figure"].
  • EXTERNAL_CLAIMS["alt text semantic levels"], and Lundgard in GUIDE_CITED.
  • check_figure.XHEIGHT_FLOOR_PT = 4.0 and x_height_fraction(path).
  • check_type_size warns when a string with a lowercase letter has an x-height under XHEIGHT_FLOOR_PT on 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. usetex text is not measured.
  • style-guide.md References: Legge & Bigelow (2011). EXTERNAL_CLAIMS["fluent print size"], RETRACTED_CLAIMS["7.5pt as the size where text is comfortable"], and Legge in GUIDE_CITED.
  • check_figure.SERIES_CONTACT_PX = 2.0, in NOT_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_set and test_same_process_small_multiples_mostly_share_at_the_ratio in tests/test_figure.py.
  • RETRACTED_CLAIMS["autoscaled small multiples landing well inside a span ratio of 2"].
  • examples/gallery.py: classifiers, abundance, dose_response and interrupted, with their PNGs and entries on the gallery page.
  • Four tests in tests/test_figure.py pinning the pair each one puts in front of check_series_color, and seven CHECKED entries in tests/test_alt_text_numbers.py for their alt text.
  • check_palette.pair_separation(color_a, color_b): cvd, cvd_kind, cvd_severity, tritan and normal for one pair.
  • EXTERNAL_CLAIMS["anomalous trichromacy the commoner form"], test_the_anomalous_share_is_the_sum_the_table_gives, and Sharpe in GUIDE_CITED.

Changed

  • check_type_size: the floor is min(TYPE_FLOOR_PT, ceiling); text over the ceiling fails. A bold, upright, one-lowercase-letter string is held to VENUE_PANEL_LABEL_PT instead. The over-ceiling [FIX] gives the authored size, floor / scale. Where no base under the ceiling lifts a script to MATH_SCRIPT_FLOOR_PT, the script [FIX] names LogFormatter() and text.usetex instead of raising the base.
  • TYPE_FLOOR_PT is 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.md References: the Machado entry says severity 1.0 is scaled to match Brettel 1997; the Nuñez entry names cividis.
  • The MACHADO comment in check_palette.py and the docstring of test_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.md References: DOIs for Anscombe (1973) and Schenker & Gentleman (2001).
  • style-guide.md References: 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() in tests/test_prose_claims.py accepts a path from the root.
  • check_line_weight holds major and minor tick marks to FURNITURE_FLOOR_PT. test_line_weight_still_does_not_measure_tick_marks becomes test_line_weight_measures_tick_marks.
  • check_line_weight holds marker outlines to FURNITURE_FLOOR_PT when _marker_outline_pt finds 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_image holds on the rims (_marks_rim) of the marks Agg draws inside their clip box and clip path (_drawn_rows). _ground_image draws everything before that artist, and a Line2D's own line (_own_line), in its axes and in each earlier axes whose box meets it (a twin's host). check_line_weight draws that ground forward on one buffer (_ForwardGround), and only for an outline that differs from its fill. _ground_image returns Agg's uint8 RGB.
  • check_line_weight reads tick widths through marker_stroke_pt, so color="none" ticks measure 0, and skips spines, ticks and gridlines on an axes with axison false and ticks and gridlines on a hidden axis.
  • check_type_size compares on-page sizes to the floor and ceiling before rounding, with _PT_TOL = 1e-6 of slack, as do the mathtext script floor and check_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_color gates every pair in a panel with a legend, as in one with marks and no line (scatter, or plot with 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_PX of 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_json and check_palette.check_json, which return audit's and check's verdict as a JSON document rather than a printed table. check_figure.AUDIT_SCHEMA and check_palette.AUDIT_SCHEMA name the wire format, and both are figure-gate/audit/1.
  • check_palette.py --json prints check_json's document instead of the table. The exit code is unchanged.
  • __all__ in check_figure.py, check_palette.py and suggest_fixes.py, listing every public module-level name.
  • CITATION.cff, carrying the Zenodo concept DOI 10.5281/zenodo.21784217. Its version is the sixth site the release bump rewrites.
  • check_figure.load_config, find_config and config_keys. load_config assigns the check_figure and check_palette constants named in a figure-gate.toml, or in a [tool.figure-gate] table in pyproject.toml. An integer constant takes a whole number, stored as an int; STYLE_SHEET takes a string and CONTENT_WIDTH_PT a number. CONFIG_FILENAMES, CONFIG_TABLE and CONFIG_ALIASES hold 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 --venues is.
  • Six rows in VENUE_WIDTH_PT, taking it from twelve to eighteen: amsart 360.0, siam 370.38, revtex 510.0, revtex-column 246.0, beamer-43 307.29 and beamer-169 398.34.
  • check_figure.DID_NOT_RUN and suggest_fixes.DID_NOT_RUN, the prefix a detail carries when the gate could not run. suggest skips a row that carries it.
  • NOT_CONFIGURABLE in check_figure.py and check_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_N and CMAP_SAMPLES. config_keys() drops from 60 keys to 55, and load_config raises with the reason rather than the "names no threshold" message.
  • A doi or a no_doi field on every entry of EXTERNAL_CLAIMS in tests/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_is and test_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 in choosing-a-form.md; Nuñez et al. 2018 and Stone, Szafir & Setlur 2014 in style-guide.md.

Changed

  • check_style_sheet returns "warn" rather than True when no figure.mplstyle is found. Advisory, so ok is unchanged.
  • check_series_color and check_colormap return "warn" rather than True when check_palette.py is not importable beside check_figure.py. Advisory, so ok is unchanged.
  • All three of those details now open with DID_NOT_RUN, and suggest returns no remedy for a row that carries it.
  • Nothing a caller could do at 0.9.0 has stopped working. griffe check against the tag reports one change, VENUE_WIDTH_PT's value, which is the six rows above, and no break in check_palette or suggest_fixes.

Fixed

  • release.yml's TeX install retries at timeout 60 and timeout 240, down from 300 and 600, and no longer sleeps after its last attempt.
  • check_style_sheet warns on a key the sheet names that matplotlib dropped while parsing, such as grid.color: #e1e0d9. It returned True for one.
  • The scale argument of audit, report and audit_json, and the return of page_scale itself, 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.md and skill/references/style-guide.md name the configuration file. Both sent a reader to CONTENT_WIDTH_PT at 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 calls load_config.
  • Heer & Agrawala 2006 changed IEEE TVCG 12(4) → 12(5), in choosing-a-form.md and in the EXTERNAL_CLAIMS entry. The pages, 701-708, were right.
  • Stone, Szafir & Setlur 2014 changed 2014(1) → 22(1) in style-guide.md, the volume and issue 10.2352/CIC.2014.22.1.art00045 resolves to. The pages, 253-258, were right.
  • docs/design.md changed the stated suite size 2190 → 2256.
  • tests/test_renderer_invariance.py sweeps every gallery figure. BUILDER_NAMES was a hardcoded eleven under a comment saying it was read off the module; it is parsed from BUILDERS now, 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 34 rows over eleven figures → 76 over twenty, in check_figure.py, docs/design.md and the sweep's own docstring. The one status flip is still orbit's ink coverage at 600 dpi.
  • check_palette.oklab_distance, cmap_back_travel and hex_to_linear's raise are exercised. Coverage of check_palette.py 86% → 88%.
  • README ## Try it changed "The second command prints a failing report" → "check-figure prints a failing report".
  • test_the_readme_names_the_one_command_that_fails and test_every_source_states_the_real_defect_count added in tests/test_docs_match_code.py.
  • pyyaml added to the dev dependency group, and to the ci.yml test leg that installs cmasher. On a clean uv sync --group dev tests/test_version_sites.py goes from 13 passed and 6 skipped to 19 passed.
  • test_a_configured_navigation_feature_reaches_the_built_page and NAVIGATION_MARKUP moved from tests/test_docs_site.py to tests/test_docs_render.py, and the four cases now depend on built_site. They skipped in every CI job, and in about half of local -n auto runs.
  • check_type_size changed its scale in the detail string from the unrounded float to two decimals, the format check_line_weight already used.
  • docs/design.md removed the claim that the colormap row passes when check_palette.py is not importable, and the "five verdicts" sentence.
  • docs/design.md changed "without a Python interpreter on PATH" → "with a bare Python interpreter and nothing installed".
  • docs/gallery.md changed 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.md changed what sets the 3.11 floor to name load_config, and removed the paragraph repeating the two floors.
  • docs/install.md, docs/how-to.md and docs/api.md removed copies of the import-line history, the py.typed note, the suggest_fixes.py note and the "default route" claim, and link to the one copy that stays.
  • choosing-a-form.md changed "a sevenfold difference" → "one bar eight times the length of the other, for values 7% apart", "the one check_figure.py fails" → "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.md and style-guide.md removed transparency as a fix for overplotting; test_transparency_does_not_move_the_overplotting_row added.
  • style-guide.md changed the Fast path's and Procedure's check_figure.py step → report(fig), the adjacent CVD figure 32.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.md Setup added suggest_fixes.py to 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.md changed "mypy runs unannotated" → "mypy runs with the strict flags off", and "Changing a threshold" → names tests/test_thresholds_are_constants.py and docs/gates.md beside tests/test_palette.py.
  • zensical.toml added favicon = "images/favicon.png", a 64px lucide/fence in #0072b2, and [project.theme.icon.admonition] note lucide/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) and report(suggest) changed to keyword-only.
  • check_figure.audit measures under the rcParams the figure's first audit saw. METRIC_RC_KEYS names them. Style sheet and the Type 3 clause of Fonts still read the live rcParams.
  • Line weight, Colormap kind, Contrast stack, Form, Mark ratio, Series color, Overplotting, Ink coverage, Contour dash and Banking walk child axes. Content inside ax.inset_axes is judged where it went unjudged before, so a figure carrying one can newly fail or warn.
  • check_figure._all_axes returns fig.axes first and descendants after, so the ax{i} names in the detail strings keep their meaning for the panels that were already numbered.
  • Line weight measures spines and gridlines, major and minor, against FURNITURE_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_rgb and check_palette.cmap_back_travel_rgb, classifying a ramp from float sRGB. The hex-taking cmap_kind and cmap_back_travel are unchanged.
  • Two gallery figures, gallery-callout and gallery-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-phase and gallery-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.py audits the sheet's own palette with check_palette, categorical and ordinal, alongside the figures. main fails on a palette row as it does on a figure.
  • check_figure.MARK_RIDE_TOL_PX and check_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_TOL and check_figure.RAMP_MIN_STEPS, the four values deciding whether a panel's colours are samples of a registered ramp.
  • check_figure.FORM_BAR_MIN_PATCHES and check_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 for demo and encoding.
  • check_figure.marker_extent_pt, the width and height in points that a plot marker actually draws, which is not markersize for every marker.
  • check_figure.marker_stroke_pt and check_figure.collection_stroke_pt, the stroke a plot marker and a scatter each 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 second Mark ratio entry, 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 reading REMEDIES by index rather than by gate sees 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 stack no longer fails a figure that uses matplotlib's per-point alpha. An alpha ramp counts as one level.
  • Text collision, Label attribution and Text readability measure a callout's string rather than its leader line.
  • Label attribution reads an annotation at the anchor its leader points to, rather than at the string. A leader drawn to the wrong curve still fails.
  • Label attribution no longer judges a panel title, axis label or colorbar label as a direct label.
  • Axis redundancy requires the panels to share limits, scale type and axis title before it calls a tick column repeated.
  • Clipping recognises off-view ticks on a child axes, so secondary_xaxis and secondary_yaxis no longer report them as clipped text.
  • Colormap kind classifies a ramp before the 8-bit round trip.
  • Colormap kind recognises a colormap the author evaluated themselves. Series drawn in colours sampled off jet, rainbow or 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.
  • Form reads bars drawn as plain Rectangle patches. A truncated baseline built by hand rather than by ax.bar now fails the row, and the two spellings return the same detail string.
  • Axis redundancy measures 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 no sharex can newly fail. The detail names repeated x tick row beside the existing repeated y tick column.
  • Line weight measures 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 size measures mathtext sub- and superscripts rather than reading the declared size, and holds them to MATH_SCRIPT_FLOOR_PT rather than to TYPE_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. usetex figures are exempt.
  • Overplotting reads a cloud drawn as plot markers with no connecting line, not only one drawn by scatter. The two spellings of the same cloud now report the same number. Figures using the plot spelling can newly warn, and two in this project's own corpus do. The detail names ax{i}.line{j} beside the existing ax{i}.col{j}.
  • Auditing one figure twice returns one verdict, and a gate called on its own reports what audit reports.
  • audit_api.py matches a reported name with lookarounds rather than \b, so a parameter change can be written down at all.
  • Line weight no longer raises TypeError on an EventCollection, 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 attribution no 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/images carries the eight figures this cycle added to the corpus.
  • gates.md carries the rule and not the argument, which its own intro already routes to the style guide. Six Fails when cells 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 under choosing-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_bumps on that entry; the release bump still refuses to run without notes.
  • uv.lock is a bump entry, anchored across its name and version lines.
  • Series color no longer reads an inset-zoom connector as a data hue. indicate_inset_zoom builds its connectors out of ConnectionPatch, and matplotlib gives each a facecolor off the property cycle although the shape it draws is a line. _data_colors_by_axes excludes them.
  • gallery-broadening sets its connectors' width itself. lw= on indicate_inset_zoom reaches the indicator rectangle and, on matplotlib 3.8, not the connectors.
  • test_a_two_line_label_carrying_mathtext_parses_per_line names the warning it guards against instead of raising on every warning.
  • The macOS CI leg runs pytest at -n 2 rather than -n auto.
  • Label attribution reads a stroke-less Line2D as marks rather than as a polyline. check_figure._series_px sends one to _marks_px, so a cloud drawn as plot(..., 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.
  • Overplotting answers a large cloud without scipy installed. The scipy-free branch of _contact_fraction enumerated every pair as a dense matrix, which on gallery.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:

Greys 4, even steps      pass        ColorBrewer Blues 4    fail
Blues 3                  pass        single hue, 5 steps    fail

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) and report(suggest) changed to keyword-only. A venue passed positionally landed in the context_axes slot, where a string is iterable and so was accepted silently, and the figure was then measured at the wrong page width.
  • audit_api.py matches a reported name with lookarounds rather than \b. The parameter names griffe reports end in ), which \b cannot 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_rgb and check_palette.cmap_back_travel_rgb classify a ramp from float sRGB. The hex-taking cmap_kind and cmap_back_travel are unchanged.
  • Two gallery figures, gallery-callout and gallery-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 stack no 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 attribution and Text readability measure 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 attribution reads 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] 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. A leader drawn to the wrong curve still fails.
  • Label attribution no longer judges a panel title, axis label or colorbar label as a direct label.
  • Axis redundancy requires 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 use sharey.
  • Clipping recognises off-view ticks on a child axes, so a secondary_xaxis or secondary_yaxis no longer reports them as clipped text.
  • Colormap kind classifies a ramp before the 8-bit round trip. winter and Wistia failed on quantisation artifacts of about 0.001 OKLab, amplified by their narrow lightness spans.

0.8.0 — 2026-08-18

What changed

  • delta_e changed what it returns: CAM02-UCS ΔE, not OKLab ×100. Same name, same signature, different number, and the sharpest edge in this release.
  • oklab_distance was added, returning exactly what delta_e returned before.
  • linear_to_cam02ucs was added: a stdlib CIECAM02, held to colorspacious within 1e-9 on identical XYZ.
  • CVD_TARGET changed 8.0 → 10.5; NORMAL_FLOOR changed 15.0 → 21.0; CMAP_WRAP_DE_MAX changed 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.
  • audit draws at MEASURE_DPI = 150 and hands the figure back on the dpi it arrived on. check_ink and check_text_readability do the same when called directly. No verdict changed at 150 dpi; verdicts at other authored dpi changed to match it.
  • DOCUMENT_TO_GATE_MAX changed 0.92 → 0.93 → 0.998 → 1.009.
  • getting-started.md is gone, split across tutorial.md, install.md and compatibility.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.8 floor is asserted against CI's matrix.
  • Seven unused markdown extensions removed from the site config; navigation.tabs, sections, path and footer set; 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 on gates.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_e changed 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_distance was added, returning exactly what delta_e returned before, for callers who need the old scale.
  • linear_to_cam02ucs was added: a stdlib CIECAM02, held to colorspacious within 1e-9 on identical XYZ by tests/test_colour_space_oracle.py.
  • CVD_TARGET changed 8.0 → 10.5 and NORMAL_FLOOR changed 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_MAX changed 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.

  • audit now draws at MEASURE_DPI and hands the figure back on the dpi it arrived on. check_ink and check_text_readability do the same when they are called directly, so a gate called on its own reports what audit reports.
  • 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.py sweeps 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_DPI the 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, and how-to.md, task-titled.
  • Reference: gates.md, cli.md and compatibility.md, the last two new, and api.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.md credited 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, and tests/test_colour_space_oracle.py pins 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.py after 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_figure no longer resolves; from figure_gate import check_figure does. The console scripts check-palette and check-figure are unchanged, and vendoring is untouched.
  • py.typed ships. The style sheet installs to figure_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 = false records that.
  • New gate: check_banking, advisory, with BANKING_SLOPE_MAX = 10.0 and BANKING_MIN_POINTS = 8. GATES gained a row and every row after Line weight moved down one, so audit() 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.7 added: 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.
  • MACHADO and simulate_anomalous added, with ANOMALOUS_SEVERITIES. The separation row takes the worst over them alongside dichromacy and names the severity its verdict came from.
  • scatter_diameter_pt added. s is a squared diameter, not an area, so Mark ratio and Overplotting both report different numbers than before.
  • Four gallery figures added: gallery-uncertainty, gallery-counts, gallery-residual, gallery-density. The corpus is eleven figures.
  • examples/gallery.py and examples/demo.py are importable. The driver, the argv read and the exit are under __main__; the builders return their figures and write nothing with OUT/out set 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.dev0 here). uv run bump-my-version bump dev drops 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, and RETRACTED_CLAIMS.
  • Corrected in alt text: the slope graph's eleven of twelve rise, the demo's reaches 0.05 by epoch 6, and the field's 28-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 simulate when 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 simulate already 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_px dropped non-finite vertices and then densified across what was left, which joins the two sides of every hole. A 100-point sine with y[40:60] = nan came 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, because Line2D fills a masked input with NaN on recache. Densifying per run of consecutive finite vertices fixes both spellings.
  • Only ax.lines was 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_px now takes scatters too, recognised by carrying sizes, which is the discriminator check_overplotting already uses and which keeps fill_between from 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 markersize side and left standing on the s side, 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 raw s.
  • 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 was nn_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 is d < 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: after adds 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.md and docs/getting-started.md, both authored pages named in AUTHORED. Nothing was duplicated in the move.
  • docs/api.md added: ::: directives read by mkdocstrings at build time, documenting fifteen functions. Eight of them gained a docstring. tests/test_api_reference.py holds the page to the modules.
  • PROSE_DOCS is derived from git rather than listed: every tracked markdown file, minus CHANGELOG.md and specs/, 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 check against the last tag, failing only when a break is not mentioned in the Unreleased section; and codespell with three ignore-words. pymarkdownlnt was measured and rejected.
  • uv run bump-my-version bump minor rewrites CHANGELOG.md, pyproject.toml, plugin.json and recipe.yaml, commits, and tags v<new>. CHANGELOG.md is first in the file list and the order is load-bearing.
  • tests/test_version_sites.py added, holding the bump config to the files it points at.
  • examples/demo.py and examples/gallery.py take an optional output directory. The default is unchanged.
  • The docs build installs --only-group docs instead of naming its dependencies inline.
  • make audit added, with specs/2026-07-30-standardized-docs-audit.md recording what each check proves and what it does not.
  • conda/README.md describes 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-gate installs the skill. Two CI checks come with it, both in the skill job.
  • Ruff and mypy run in CI. Neither existed before. Thirteen findings were fixed rather than suppressed; two carry a noqa with the reason beside it. per-file-target-version reads check_palette.py against the 3.8 grammar, and E741 is ignored because l is the OKLab lightness channel.
  • _back_travel takes 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), matching check_figure.audit(). It returned (rows, ok) before. If you unpack it, swap the names.
  • requires-python changed >=3.9 → >=3.11. check_palette.py still runs on 3.8 when vendored, and matplotlib stays floored at 3.8.
  • GATES added: one registry holding the twenty rows with their functions, advisory flag and arguments. ADVISORY_GATES is derived from it.
  • audit() and check() gained docstrings. They were the only functions in either module without one.
  • NO_GUIDANCE is empty: Clipping and Ink coverage have guidance, with a test to keep a future re-entry deliberate.
  • tests/test_prose_claims.py added, sweeping the four prose documents. EXTERNAL_CLAIMS carries claims about the world with a source and a date.
  • KNOWN_DISAGREEMENTS is compared only against colormaps the running matplotlib has. A broken cmasher skips with its reason instead of erroring.
  • conda/recipe.yaml and conda/update_recipe.py added, with tests/test_conda_recipe.py holding the recipe to pyproject.toml.
  • Corrected: RdBu's poles (#b1182b and #2065ab are t=0.098 and t=0.899, not the ends), five CMAP_* 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.py still 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 carries check_figure.py too.
  • 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:

  • #b1182b and #2065ab were described as RdBu's poles. They are the map at t=0.098 and t=0.899. Its actual ends, #67001f and #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 about check_figure.py. They are defined in check_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. GATES holds the twenty rows with their functions, their advisory flag and the arguments they need. audit() builds its rows from it and ADVISORY_GATES is derived from it, where both were separately maintained lists of the same names.
  • Both entry points are documented. audit() and check() 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_DISAGREEMENTS is scoped to the registry it is about. test_only_the_three_known_colormaps_disagree_with_cmasher asserted that all three of its adjudicated colormaps still disagree. Two of them, managua and vanimo, 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 dev with 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 under skill/scripts/ constructs a ListedColormap, 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. Fonts moves to 19 and Alt text to 20. A heatmap drawn in jet was a PASS in every release before this and is a FAIL now.
  • cmap_kind() added to check_palette.py, stdlib only, with CMAP_SAMPLES = 256, CMAP_QUALITATIVE_N = 40, CMAP_SPAN_MIN = 0.02, CMAP_BACKTRAVEL_MAX = 0.02 and CMAP_WRAP_DE_MAX = 3.0. misc is the only outcome that fails; jet, rainbow, hsv and gist_ncar land there.
  • A qualitative colormap is routed to the palette gates for its separation rows only.
  • ANONYMOUS_CMAP_NAMES added, 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.css reaches the page again: the scheme rules no longer carry a :root prefix that matched nothing.
  • GUIDANCE_ANCHORS added, binding eighteen of the twenty gates to a passage. Clipping and Ink coverage are 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.py skips per test rather than at collection, so the test count is the same everywhere. The cmasher differential runs in CI.
  • main is 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_colormap is row 18, directly after Contour dash, which moves Fonts to 19 and Alt text to 20. It harvests every artist in ax.images and ax.collections whose get_array() is not None, 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, in check_palette.py, stdlib only. It samples CMAP_SAMPLES = 256 levels, converts to OKLab, and reads the lightness channel. Under CMAP_QUALITATIVE_N = 40 levels is qualitative. A span under CMAP_SPAN_MIN = 0.02 is 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: under CMAP_BACKTRAVEL_MAX = 0.02 over the whole map is sequential, under it over both halves is diverging, or cyclic when the ends are within CMAP_WRAP_DE_MAX = 3.0 in 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, managua and nine cmr.* 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_color reads 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 for z³ − 1 in 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". turbo passes as diverging: its lightness profile genuinely is diverging-shaped, and its real defect is hue banding, which a lightness-only measure cannot see. Wistia is classified misc and is sequential by kind; back-travel divides by span, and narrow-span maps get noisy ratios. Both are written down in specs/2026-07-28-colormap-kind-gate-design.md with 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 in test_docs_match_code.py, the paint in test_docs_render.py.

  • palette.css had been reaching nothing. Prefixing both scheme rules with :root won a specificity fight that did not exist: Zensical sets data-md-color-scheme on <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. --strict does 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 to narenp12.github.io/choosing-a-form/. Every href in the built HTML is now resolved the way a browser does, against the base path site_url publishes under.

  • A bare filelock import 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, #898781 and "171 tests" were each right when they were typed too. Every name is now resolved against check_figure and check_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.py and the gallery page had been updated. All three are now held to the number of finish() calls in the script.

  • Neither guide had a cyclic colormap, while the gallery shipped a twilight phase portrait. ### Cyclic: twilight, as shipped and ### Which kind, and the key it takes are 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 against cmap_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_ANCHORS binds eighteen of the twenty gates to a passage that has to still be there. Clipping and Ink coverage are 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.md has 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 a ListedColormap that 3.8.4, 3.9.4 and 3.10.0 call from_list and 3.11.1 calls unnamed. 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 and gallery-field.png went with it. ANONYMOUS_CMAP_NAMES holds 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.py opened with a module-level pytest.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() against cmasher.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.

  • main is 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 a main that 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 in main for 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 dash fires on any negative level, asked of the strokes the set drew rather than of negative_linestyles. It required every level to be non-positive before, which is the one shape a signed field never has.
  • check_mark_ratio measures scatter and plot markers in one unit. The ratio moves by 4/π.
  • alt_metadata(fig, path) takes an optional path and returns the key that format has, or None for the formats that have none. Called without a path it returns Description, as every earlier version did.
  • ADVISORY_GATES added as the one list. Overplotting and Contour dash are 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 #56B4E9 for body links; light mode keeps Okabe-Ito blue #0072B2.
  • Muted ink changed #898781 → #777570 in the guide's table, matching what figure.mplstyle ships. The old spelling stays in INK_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.
  • _halo no longer returns "no casing" when matplotlib's private _gc moves.
  • Smaller: --venues runs without matplotlib; the dual-axis message says "two data scales"; ordinal() no longer divides by zero at n=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: contour over data spanning zero draws levels either side, and matplotlib dashes the negative half. A sin(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. Overplotting and Contour dash return only True or "warn", but the README table gave both a "Fails when" and the prose counted five advisory rows against an actual seven. ADVISORY_GATES in check_figure.py is now the one list; the table's tags, the count in the prose, and the claim that none of those functions has a returning-False path are all tested against it.

  • check_mark_ratio measured two mark kinds in different units. Scatter s is an area in pt²; markersize is 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 mixing scatter with plot(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_metadata warned on every PDF save, and crashed on every jpeg. The documented call — the one in SKILL.md, in the README and in both examples — is savefig(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
pdf 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, which figure.mplstyle stopped setting when check_text_readability failed 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 in INK_TOKENS so 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 through rc_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 #fcfcfb surface.

  • "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 (#009E73 vs #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 asking check_palette.check(..., all_pairs=True) for the largest passing count, and the prose and the constant are held to it.

  • _halo reads a matplotlib internal and failed silently. Stroke keeps its kwargs in a private _gc and 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 a foreground, and a direct test makes an upstream rename a red suite rather than a quiet regression.

  • Smaller, same shape: --venues no longer requires matplotlib to print a table of numbers; the dual-axis message says "two data scales" rather than "two y scales", since twiny lands there on the same argument; the appendix's ordinal() no longer divides by zero at n=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 because style-guide.md is 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 #0072B2 is 5.19:1 on white but 3.10:1 and 3.77:1 on the two dark backgrounds Zensical ships (classic at hsl(225, 15%, 14%) = #1e2129, modern at hsl(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 #56B4E9 at 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.md href, 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.py enumerates 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, and test_docs_match_code.py now 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 RdBu poles and midpoint, and the viridis endpoint. Every other cell in those tables is recomputable — a contrast ratio goes back through contrast() — 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_metadata call this release fixes. savefig(path, metadata=alt_metadata(fig)) — the form that warns on every PDF save and that SVG rejects. SKILL.md and both examples were corrected when the fix landed; style-guide.md was 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, omitting Contour 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 against audit for 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 against audit: 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 order audit does.

  • 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 what figure.mplstyle renders, 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 against contrast().

  • The grayscale separations were labelled ΔL and are not. ΔL 0.011 and ΔL 0.264 are 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 against relative_luminance(); the aside giving the OKLab equivalents is checked against linear_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.md states outright that every alt text on the page is what was passed to describe(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 beside check_figure.py, which is the first location _style_sheet probes. Through 0.1.3 the wheel carried skill/scripts and nothing else, so on uv add figure-gate there 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 with plt.style.use forgotten 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_SHEET is 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. None keeps the existing behaviour: beside the script, then assets/ 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's assets/ 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 in pyproject.toml is 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_THRESHOLD is 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 inside check_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) while audit() 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.dpi to the authored dpi times the display's device pixel ratio when the figure is created, and _renderer kept 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 conftest pins Agg and so does every script in examples/ — 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.py table, and the test that checks that table against what audit() 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-attestations uploaded 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_overplotting and check_contour_dash.
  • figure.mplstyle sets axes.prop_cycle to the six Okabe-Ito series slots, and pdf.fonttype: 42 / ps.fonttype: 42. Yellow and black are held out.
  • xtick.color/ytick.color changed #898781 → #777570, 3.59:1 to 4.6:1 on white.
  • audit(fig, venue=...) added for twelve known venues, with python check_figure.py --venues listing them. CONTENT_WIDTH_PT still wins for anything not in the table.
  • describe(fig, ...), alt_metadata(fig) and check_alt_text added, advisory.
  • audit(fig, context_axes=[ax]) added: a filled backdrop is a context surface rather than data ink.
  • check_palette.py learns --ink, exempting listed hexes from the chroma-floor and lightness-band rows.
  • scipy is optional, a fast extra. uniform_filter is replaced by a numpy box blur, KDTree is gone from label attribution, and check_overplotting falls 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_redundancy skips axes with axison false and counts only visible tick labels.
  • check_ink decides emptiness structurally rather than by pixel fraction.
  • examples/gallery.py added: six figures, each audited, with CI failing if any figure fails.
  • skill/references/choosing-a-form.md added, plus a step in SKILL.md.
  • Decided and written down: identity does not ride on label colour, and a legend entry is not a direct label. examples/demo.py labels 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 and set_rlabel_position only 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 own figure.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_redundancy no longer reads furniture that never renders. Three imshow panels at axis("off") were told to "use sharex/sharey" on the strength of the tick Text objects matplotlib keeps for an axis it is not drawing. Axes with axison false are skipped, and the tick clause now counts only visible labels.

  • check_ink can 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_weight has 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_readability measures 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.color shipped at 898781, which is 3.59:1 on white — under the text threshold on every figure in the repo. Now 777570 at 4.6:1, still below the 7.94:1 axis label, so the hierarchy axis label > tick label > grid survives.
  • examples/demo.py was the first thing it failed. All three direct labels sat on their own curves — 'Baseline' on data ink over 17% of its box — while check_label_attribution passed 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 through page_scale like 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 defaults pdf.fonttype/ps.fonttype to 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 in font.<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.mplstyle now sets pdf.fonttype: 42 and ps.fonttype: 42.

Venue content widths

  • audit(fig, venue="neurips") replaces hand-measuring CONTENT_WIDTH_PT for twelve known venues (NeurIPS, ICLR, ICML, ACL, IEEE, Nature, LaTeX article, and the column widths of the two-column ones). python check_figure.py --venues lists them. CONTENT_WIDTH_PT still 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_metadata produces the metadata= dict for savefig, 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_other stays 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.png had 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 scipy import had quietly broken it. scipy.ndimage.uniform_filter is replaced by a separable cumulative-sum box blur in numpy; scipy.spatial.KDTree is gone from label attribution entirely; check_overplotting uses cKDTree when it is importable and an O(n²) numpy path when it is not. scipy is now an optional fast extra. 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.md argues 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_ticks the way check_clipping already did;
  • check_ink measured 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_weight measured a colorbar's own 0.4pt dividers;
  • _artist_kind called plot(..., 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_attribution was 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_overplotting detects scatter marks that merge into a blob. For each scatter (PathCollection with 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." New audit(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 (no context_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. New check_contour_dash warns; pass linestyles="solid" on signed data. Style guide note added.
  • check_palette.py learns --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. Mirrors check_figure's INK_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 ax guard because a legend child's .axes is 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 it scatter(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.mplstyle sets axes.prop_cycle to 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 inherited tab10. 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_yaxis with 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.mplstyle are not the ones in effect. Catches the #-is-a-comment trap, a forgotten plt.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 collision compares 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.py defaulted to #fcfcfb, a surface figure.mplstyle never 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, --surface still available for a genuinely tinted page.
  • tests/test_docs_match_code.py parses the guide's contrast table and checks every quoted number, and every † marker, against contrast(). The drift above is now a test failure rather than something noticed in a year.
  • placed_frac on audit()/report(). A figure placed at 0.48\textwidth was measured as if it were full width and certified at twice the type size it shipped at. Passing placed_frac without CONTENT_WIDTH_PT raises rather than silently assuming 1.0.
  • Mark ratio sees line markers. It read only ax.collections, so markersize=3 beside markersize=30 passed 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.mplstyle carries the mark and output defaults: lines.linewidth, lines.markersize, axes.linewidth, patch.linewidth, legend.handlelength, errorbar.capsize, axes.axisbelow, plus figure.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/titleweight annotated 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.md plus the full style guide).
  • 49 tests, including per-gate failure cases and a guard against the style sheet's colors silently not applying.