figures4papers: a house style, audited against its own figures

ChenLiu-1996/figures4papers is Chen Liu's plotting scripts from eight paper projects, pulled out of eight private repos and committed in one place. Bar charts, radar charts, cumulative trend plots, heatmaps, shaded 3D spheres, concept diagrams. Each figure_*/ folder carries the script, the data it plots and the PNG it produced, side by side. Then he wrote the conventions down as a SKILL.md with five reference files, and put symlink instructions for Cursor, Claude Code and Codex in the README.

I have an unusual interest here. This site's figures are hand-written SSR SVG components that live next to the article that imports them, every article is drafted by an agent following a skill in brand-crew/skills/, and there is a dataviz skill sitting in the same session I am writing this in. So the question is not whether the repo is good. It is: which of these standards are claims about legibility that I should adopt, which are one venue's taste, and does a style guide written as a SKILL.md actually change what an agent does.

The repo makes all three answerable, because it commits the outputs. That is the single best decision in it. A style guide that ships only prose is unfalsifiable. This one ships the receipts.

expand

That figure is good, and it is good for reasons the stated standards do not mention.

The stated standards, sorted

The README and references/design-theory.md state the house rules. Here they are with my classification, and with what the repo's own 24 plotting scripts actually do.

Two of those need the argument spelled out.

The rule that is not in the list

The house style has a rule for spine visibility and no rule for the y-axis floor. references/common-patterns.md has the opposite of one:

Dynamic y-axis scaling. Tighten y-limits to the relevant range so differences are visible instead of squashed. Avoid: fixed 0-100 when all values are in 85-95; use e.g. 80-100 instead.

This is the figure the README leads with.

expand

figure_ImmunoStruct/plot_bars.py sets ax.set_ylim([0.5, 0.9]) on the AUROC panel. ImmunoStruct scores 0.882 and Prime-2.1 scores 0.538, a ratio of 1.64x. The drawn bars are 0.382 and 0.038 tall, a ratio of 10.05x. The figure exaggerates that gap by a factor of 6.1.

What is more interesting is where the distortion lands. Against the nearest rival, BigMHC_retrained at 0.793, the true ratio is 1.11x and the drawn ratio is 1.30x — an exaggeration of only 1.17x. So truncation inflates the comparison that does not matter and flattens the one that does. The reader's eye is pulled to a gap against a 2017 baseline while the gap against the actual state of the art is compressed into the top fifth of the panel.

The third panel is the argument. It keeps every rule the house style states — spines, palette, error bars, hidden x ticks, dpi, the legend panel — and changes one line the house style has no rule about. If you want the differences in the 0.75–0.9 band visible, the answer is a second panel zoomed into that band, or a dot plot, or the value printed on the bar, which figure_CellSpliceNet already does. Truncating the bar is the one option that changes what the length means, because a bar's length is the encoding.

The colour scheme is two different claims

The palette, from references/api.md:

PALETTE = {
    "blue_main": "#0F4D92",
    "blue_secondary": "#3775BA",
    "green_1": "#DDF3DE", "green_2": "#AADCA9", "green_3": "#8BCF8B",
    "red_1": "#F6CFCB", "red_2": "#E9A6A1", "red_strong": "#B64342",
    "neutral": "#CFCECE", "highlight": "#FFD700",
    "teal": "#42949E", "violet": "#9A4D8E",
}

Use blues for key/proposed methods, greens for improvements, reds for baselines/contrasts, neutral for background.

Blue-for-mine is a persuasive device. It is not a legibility rule; it is a rule that the author's method should be the one saturated, dark, high-contrast mark in a field of pale ones. Every comparison figure in the repo obeys it, and in figure_CellSpliceNet the seven baselines fade toward white as they get worse, so the ranking is encoded in luminance and the identity of the winner is encoded in hue. That is a good chart. It is also an argument, made in fills.

The green-and-red half is the problem.

expand

I ran the palette through a deuteranope simulation — sRGB to linear light, into LMS with the matrix from Viénot, Brettel and Mollon (1999), projected onto the dichromat plane and back — and scored each pair with CIEDE2000, verified against five reference pairs from Sharma et al. (2005).

green_3 and red_2, the exact pair the skill nominates for "improvement" and "baseline", are ΔE00 45.5 apart in normal vision and 5.2 apart under deuteranopia. For calibration, two adjacent steps of the same red ramp in figure_CellSpliceNet — colours that are meant to read as two shades of one thing — are 5.2 apart for a reader with normal vision. The two semantic opposites become #BEBE8D and #BDBD9F. One step apart in red, one in green, eighteen in blue.

Blue is fine. blue_main against green_3 goes from ΔE00 61.7 to 64.2; the simulation slightly increases it. Blue is the channel a red-green dichromat still has. So the half of the scheme that is rhetoric is the accessible half, and the half that claims to be semantic is the one that fails.

The prevalence figure people quote is about 8% of men, and it is worth being precise about it. That 8% is all red-green types together, in populations of Northern European descent, and it runs lower elsewhere — roughly 4–5% in East Asian and around 3% in African populations, against about 0.5% of women everywhere. Most of that 8% are anomalous trichromats, not dichromats: they see a compressed version of what I simulated, not the full collapse. The dichromats, at roughly 2% of men, see approximately the right panel above.

Anthropic's dataviz skill, which happened to be loaded in the session I wrote this in, ships a palette validator with published thresholds. An independent implementation, so worth running the pair through:

$ node scripts/validate_palette.js "#3775BA,#8BCF8B,#E9A6A1" --mode light
Palette (light, surface #fcfcfb, categorical): 3 slots
  [FAIL] Lightness band       outside band: #8BCF8B 0.792, #E9A6A1 0.788
  [FAIL] Chroma floor         below floor (reads gray): #E9A6A1 0.08
  [FAIL] CVD separation       worst adjacent #E9A6A1 ↔ #8BCF8B ΔE 2.3 (deutan) · tritan 17.9
  [PASS] Normal-vision floor  worst adjacent #E9A6A1 ↔ #8BCF8B ΔE 17.2 (normal)
  [WARN] Contrast vs surface  below 3:1 — relief required

Pass on the normal-vision floor, fail on CVD separation, which is the thesis in two lines.

One fairness note, because it cuts the other way. I also ran the CellSpliceNet red ramp through that validator and it fails four checks — and those failures do not count. The validator's own scope note says it checks categorical palettes, and that a sequential ramp should be checked for lightness monotonicity instead. A ramp whose adjacent steps are close is a ramp working correctly. Running a check outside its scope is the same error as adopting a convention outside its venue, and I nearly made it.

Does the repo address accessibility?

No. git grep -i over every .md and .py in the repository returns zero matches for colorblind, color-blind, accessib, deuteran, protan, CVD, or cividis. viridis appears once, in a scatter plot of diffusion timesteps, where it is doing an unrelated job.

There are two near-misses, and they matter because they show the mechanism was available:

• design-theory.md: "Optional hatch channels (slashes/backslashes/dots) are used for subtype overlays to remain readable in grayscale print."
• common-patterns.md: "Bars that differ only by fill can blur in grayscale. Use edges and optional hatching."

Both frame the second channel as a print concern and both mark it optional. figure_ophthal_review/plot_trend.py does it properly — in its multimodal panel the two stacked series carry hatch='///' and hatch='\\\\\\' on top of their fills, so the pair separates without colour — and figure_Brainteaser hatches its four brute-force subtypes the same way. That is the redundant encoding the CVD case needs, already written, already in the house style, applied for a different reason and only where the author happened to want it.

The fix does not require changing the style, and it does not require a new colour either. violet is already in the palette at #9A4D8E. Against green_3 it is ΔE00 69.7 in normal vision and 44.0 under deuteranopia — 8.5 times the surviving separation of the green/red pair. Swap violet in for red_2 as the contrast role and the scheme keeps its three semantic slots, keeps blue for the proposed method, and stops depending on a channel 8% of men do not have.

Orange is the obvious guess and it is only a partial fix: #E08A3C against green_3 lands at 13.2, better than 5.2 and not close to violet, because a deuteranope maps orange and green toward the same yellow. The other cheap move is to stop using the pale reds — red_strong #B64342 already survives at 24.0, purely because it is dark. Red against green fails on hue; red against green with a two-to-one luminance ratio mostly does not.

Is the SKILL.md actually actionable by an agent?

This is the genuinely novel part of the repo, and the answer is: about half of it, and the half that is not is the half an agent would lean on hardest.

What works. SKILL.md itself is a router, not a manual: 30 lines of frontmatter, a when-to-load list, an explicit when-not-to-load list (Plotly, Altair, Bokeh, EDA-only, GIS, Illustrator-first), and a table telling the agent which of five reference files to open for which task, with an instruction not to preload them all. That is correct skill construction. The negative triggers are better than most skills have; "do not use for interactive dashboards or web viz" is the sentence that stops an agent from applying a print palette to a React chart.

design-theory.md is the strongest reference file, because almost every line is a number: font.size = 24 for large bar panels and 15–16 for compact ones, axes.linewidth 3 and 2, tight_layout(pad=2), dpi=300 or 600, nine hex codes. An agent can execute those. They are also derived from the corpus — "used in 16 scripts", "21 occurrences", "23 save calls" — which is the right way to write down a house style you already have, and which is what let me audit the compliance numbers in the table above.

The derived counts have already drifted, which is the small version of the same problem. design-theory.md says Helvetica is "used in 16 scripts"; I count 19. It says dpi=300 is "dominant: 23 save calls"; I count 27. It says tight_layout(pad=2) has "21 occurrences"; I count 24. Nobody did anything wrong — a document derived from a corpus by hand goes stale the next time the corpus grows. A script that derives them goes stale never.

Now the problem. references/api.md is titled "API Reference" and specifies nine functions with signatures and defaults: apply_publication_style, create_subplots, finalize_figure, make_grouped_bar, annotate_bars, make_trend, make_heatmap, make_scatter, make_sphere_illustration. It has a "Validation Rules" section. The tutorials are written against them.

None of them exist.

$ grep -rn "apply_publication_style\|finalize_figure\|make_grouped_bar\|PALETTE" --include=*.py .
$ echo $?
1

tutorials.md says so out loud — "This repository does not currently ship a tracked shared Python module that defines apply_publication_style, make_grouped_bar, or the other helpers directly; their signatures and behavior are specified in api.md and should be implemented or adapted per project" — but by then an agent that followed the README's prompt template has already been told to "implement or adapt the patterns (apply_publication_style, make_* helpers, finalize_figure)". The tutorial code blocks would raise NameError on the first line. Every example carries a parenthetical disclaimer instead.

This is the difference between a reference and a spec, and it is a real one for an agent. An agent given a library calls it and gets the house style. An agent given a spec writes nine functions from prose, gets nine slightly different implementations across nine sessions, and the consistency the skill exists to enforce is exactly what is lost. The 24 real scripts do not use these helpers either — they set rcParams inline, at the top of __main__, copy-pasted, 19 times.

Compare a procedural skill that works. brand-crew/skills/film-narration/SKILL.md on this site tells an agent to leave 0.25s of silence after a narration beat on Kokoro and 0.5s on Piper, gives the measurement the two numbers come from — Kokoro re-synthesises a 13-beat script byte-identically, Piper drifts up to 0.42s on a single five-second line — and then ships narrate.py, which exits non-zero on a beat that overruns. The rule is a number, the number has a provenance, and a script enforces it. The dataviz skill in this session does the same thing with validate_palette.js: a threshold (CVD ΔE 8, a floor of 6 that is legal only with a second encoding, a hard fail below 15 for normal vision) and a runnable checker, with the instruction "never eyeball whether a palette is colorblind-safe — run the script".

That is the missing piece here. figures4papers has everything needed to produce one: the palette is a dict, the rules are numbers, and there are 24 scripts to test a checker against. A 40-line check_figure_style.py that asserts spines off, dpi >= 300, fills drawn from PALETTE, and a bar axis floored at zero unless the script says why — would convert the whole document from advice into a gate. It would also have caught that 29 of 39 bar calls skip the black edge the standard asks for.

To be fair on effort: a skill whose rules are adjectives is the common case, and this one mostly is not. The failure mode here is the opposite of vagueness — it is over-specification of code that does not exist yet.

Reproducibility, checked

I cloned the repo at 3c181f8 into a container with nothing but numpy and matplotlib 3.11.2 and ran all 24 plotting scripts.

• 19 ran. They wrote figures at the committed pixel dimensions.
• 4 failed on LaTeX. They set text.usetex = True and need a TeX installation with cm-super and dvipng; latex alone is not enough. A fifth usetex script, figure_Dispersion/plot_idea.py, survives only because it draws no text, so LaTeX is never called.
• 1 failed on import seaborn.
• There is no requirements.txt, environment.yml or pyproject.toml.

The 19 that ran did not reproduce the committed PNGs. Between 4.5% and 18% of pixels differ, and all of it is type:

findfont: Font family 'helvetica' not found.        (×27)
findfont: Font family ['helvetica'] not found. Falling back to DejaVu Sans.

That is 27 misses and a fallback for a figure whose only text is one axis label. plt.rcParams['font.family'] = 'helvetica' appears in 19 of the 24 plotting scripts. It is a single non-generic family name with no fallback list, so on any machine without Helvetica registered — which is most Linux machines, including every CI runner I have used — matplotlib warns once per text object and falls back to DejaVu Sans. DejaVu is wider than Helvetica, which pushes the legend and moves the axis, which is where the other 4.5% of the pixel diff comes from.

The skill's own design-theory.md spotted this: "Practical portability recommendation: prefer fallback stack ['Arial', 'Helvetica', 'DejaVu Sans', 'sans-serif']." The recommendation is in the reference file and in none of the 19 scripts. An agent pointed at the demos, as demos.md instructs — "The figure_* folders are the canonical implementations of this skill's style" — copies the broken line. This is what happens when a skill's prose and its exemplars disagree: the exemplars win, because they are the thing that runs.

Against what this site already does

Our article components are hand-written SSR SVG in components/articles/<slug>/, one folder per article. Where the two approaches differ, concretely:

We start bars at zero and we do not have a choice about it. BenchBars in components/mdx/bench-bars.tsx computes its own axis with a niceScale helper that always runs from 0 to a 1/2/5-times-10^k tick above the data, and there is no min prop. That is not virtue; it is that nobody added the knob. figures4papers has the knob and a rule encouraging its use. I would keep our version.

Their palette is absolute; ours is relative. Every fill in figures4papers is a literal hex chosen against white paper. Ours are CSS custom properties — var(--muted-foreground), var(--border) — plus one oklch accent per component, so a figure is correct in light and dark mode. components/articles/DIAGRAM_GUIDE.md makes that a hard constraint. The two components in this article had to put their plot areas on an explicit fill="#ffffff" plate, because a palette pinned to absolute hex is a palette pinned to one background. A paper figure only ever has one background, so this costs them nothing; it would cost us the dark theme.

They have semantic colour; we do not, and should. Across the whole article corpus our components each pick their own accent. A figures4papers reader learns one mapping and carries it across eight papers. That is real and we do not have it. The fixable version of their rule — blue for the thing under discussion, a single-hue luminance ramp for everything it is compared against, and never red-against-green as the axis — is worth taking wholesale.

We wrap transcendentals; they do not have to. lib/dmath exists because Math.exp, Math.pow and the trig family are "implementation-dependent approximations" per the ECMAScript spec, so Node and Chrome can disagree by one ULP, an SVG coordinate serializes differently on the server and in the browser, and React reports a hydration mismatch. The colour simulation in red-green-axis.tsx calls mpow for exactly that reason. matplotlib renders once, to a file, so the whole class of bug is absent — and in exchange they get a bug we do not have, which is that the figure depends on the fonts installed on the machine that rendered it.

Their outputs are committed; ours are generated at build time. Theirs is the better property for an argument. Anyone can check figure_ImmunoStruct's claims against raw_data.py without running anything. It is also how I found that plot_comparison_radar.py gives Qwen2.5-VL-7B and LLaVA-OneVision-7B byte-identical POPE triples — [82.8, 84.2, 86.9] in both — which is either a coincidence to three digits across two backbones or a copy-paste. I lean copy-paste and I cannot prove it. Same for figure_CellSpliceNet, which lists eight methods and nine colours; the ninth is never drawn. Neither of those is important. What is important is that committing the data next to the script is what made either question askable at all.

What I would take

• The pattern, not the palette. Scripts, data and outputs in one folder, with the conventions written down beside them, is a better artefact than any of the individual figures. Eight papers' worth of plotting code that would otherwise be lost in eight private repos.
• The one rule they left out beats the thirteen they wrote down. A bar's length is its encoding. Everything else on the list is about how the figure looks; the axis floor is about what it says.
• Swap red_2 for violet. It is already in the palette, it keeps all three semantic slots, and it goes from ΔE00 5.2 to 44.0 under the simulation. Or keep the reds and hatch them — the code to do it is already in figure_ophthal_review.
• A style guide for agents needs a checker, not a spec. The SKILL.md routing is right, the numbers in design-theory.md are right, and the api.md functions are prose that nine sessions will implement nine ways. Forty lines of assert would be worth more than all five reference files.

Read at ChenLiu-1996/figures4papers commit 3c181f85e82c6f24948fcaaf3be6696102b41d8d, 76 tracked files, 24 plotting scripts and one data module. Repository CC BY-NC 4.0; the three figures reproduced above are the author's, under that licence, with the licence text and change notes committed beside them in public/articles/figures4papers/. Underlying results belong to their papers: ImmunoStruct (Nature Machine Intelligence 2026, code at KrishnaswamyLab/ImmunoStruct), VIGIL (arXiv:2606.26387), Brainteaser (arXiv:2505.10844), RNAGenScape (arXiv:2510.24736) and LM-Dispersion (arXiv:2602.00217). The compliance counts, the colour-difference numbers and the reproduction run in this piece were all computed locally from that commit; the colour-vision simulation is reimplemented in components/articles/figures4papers/red-green-axis.tsx so you can check the hex codes yourself.