Figure Design

Figure Design

Overview

Guide the creation of a research figure with the same discipline Eureka applies to everything else: gates before rendering, iron laws that do not bend, a hard prohibition on chart junk, and a fresh-eyes subagent review after every figure. A figure is an argument — every pixel either advances it or distracts from it.

Core principle: A peer reviewer spends 3 seconds on a figure before forming an opinion. Those 3 seconds decide whether they read the caption, the text, or the paper at all.

The Iron Law

NO FIGURE WITHOUT A GENERATING SCRIPT.
NO SUBMISSION WITHOUT COLORBLIND-SAFE PALETTE.
NO DEFAULT MATPLOTLIB STYLE IN A TOP-JOURNAL SUBMISSION.

Writing a figure means writing a script that produces it deterministically. Picking a palette means picking one that 8% of male readers can still decode. Setting a style means setting it once at the top of the script and never editing the output manually.

When to Use

Use this skill when:

• The user says "make a figure", "draw fig X", "plot the results", "update the brain map", "the figure looks wrong"
• A Results section is being written and a figure is needed
• An existing figure failed reviewer feedback or journal submission
• A multi-panel composite figure is being assembled

Do NOT use when:

• The user is doing pure data analysis with no figure output (no skill needed)
• The user wants to verify figure integrity post-hoc (use eureka:claims-audit Part B)
• The user is writing a manuscript section (use eureka:manuscript-writing)

Checklist

You MUST create a task for each of these and complete them in order:

1. Determine figure purpose — ask the user: what argument does this figure advance? One sentence.
2. Identify target journal — ask the user, or check CLAUDE.md / the manuscript. Different journals have different column widths, fonts, formats.
3. Select chart type — match the purpose to a chart type (see Chart Type Selection Gate below)
4. Set global style ONCE — apply_paper_style()-equivalent at the top of the script (font family, TrueType embedding, DPI, spine style)
5. Render the figure — write the script; run it; inspect the output
6. Apply iron laws — typography, color, layout, export format (see Iron Laws below)
7. Inline self-check — run through the Red Flags list
8. Dispatch figure-reviewer subagent — per figure, after the inline check passes
9. Act on feedback — fix issues; re-render; re-dispatch until approved
10. Commit script + output — both the .py/.R and the .pdf/.svg go to git

Chart Type Selection Gate

Before writing any plotting code, state the figure's purpose in one sentence and select the chart type from this table. If your purpose doesn't match any row, stop and ask the user to clarify.

| Purpose | First choice | Acceptable alternative | Avoid | |---|---|---|---| | Compare ≤5 groups on one metric | Horizontal bar chart | Grouped vertical bar | Pie chart, 3D bar | | Compare >5 groups on one metric | Dot plot, lollipop chart | Heatmap (if >10) | Stacked bar, spaghetti line | | Show distribution of a single variable | Violin plot, histogram | Box plot with raw points overlaid | Bar of mean only (hides spread) | | Show distribution across groups | Violin + strip, raincloud plot | Box + swarm | Bar chart of means | | Show trend over time (continuous) | Line plot with CI band | Scatter + LOESS | Bar chart with time on x-axis | | Show relationship between 2 continuous variables | Scatter + regression line | Hexbin (if N is large) | 3D scatter | | Show rank ordering | Dot plot, horizontal bar | Slope chart (if 2 timepoints) | Pie chart | | Part-to-whole (few categories, one total) | Stacked horizontal bar | Tree map | Pie chart with >3 slices, donut chart | | Show flow / transition | Sankey diagram, alluvial plot | Chord diagram | Network diagram with arbitrary arrows | | Show spatial pattern (brain, map, chip) | Heatmap on native coordinates | Glass-brain projection (neuroscience) | Volume rendering for 2D questions | | Show matrix of pairwise relationships | Heatmap with clustering | Correlation matrix with dendrogram | Separate scatter plots per pair | | Show two metrics simultaneously | Scatter with size encoding | Dual-axis line (only if scales compatible) | Dual-axis with unrelated scales |

Anti-patterns (never use these):

• 3D bar / 3D pie charts — the 3D projection distorts comparison
• Rainbow / jet colormap for sequential data — not perceptually uniform, not colorblind-safe
• Gradient fills for categorical colors — implies ordering where none exists
• Dual y-axes with unrelated scales — invites misleading visual correlation
• Pie charts with >3 slices — angle comparison is harder than length comparison
• Dynamite plot (bar of mean + error whisker with no raw data overlay) — reviewer-flagged top-10 mistake per eLife (Ten common statistical mistakes). Hides distribution, misrepresents spread, biases the eye to means. Overlay raw points or switch to violin/box when N per group ≤ 50

Iron Laws

These apply regardless of tool, field, or journal:

1. Typography: sans-serif, 5-7pt, one family per paper

• Font family: Arial or Helvetica (Nature, Cell, most STEM). Helvetica specifically for Science family. Never Comic Sans, Times, Courier, or decorative fonts.
• Size range: 5pt minimum, 7pt typical for axis labels/tick labels, 8-9pt for panel labels. Anything below 5pt is unreadable in print.
• Consistency: same font family across ALL figures in a single paper. Mixing Arial and Helvetica across figures is a reviewer's cheap hit.
• TrueType embedding (matplotlib): set plt.rcParams['pdf.fonttype'] = 42 and plt.rcParams['ps.fonttype'] = 42. Default Type 3 fonts are rejected by most journals.

2. DPI / resolution: 300 minimum raster, vector preferred

• Vector formats (PDF, SVG, EPS) are preferred for anything with lines, text, or geometric shapes (scatter plots, bar charts, line plots).
• Raster formats (PNG, TIFF) only for pixel-based content (microscopy, photographs, brain volume renderings). Minimum 300 DPI at final print size. 600 DPI in the save command gives headroom.
• Never JPEG for scientific figures — compression artifacts around text and edges.

3. Color: colorblind-safe, semantic, minimal

• Qualitative (discrete categories, ≤8 items): Okabe-Ito palette, tol-bright palette, matplotlib tab10. All colorblind-safe.
• Sequential (ordered magnitude): viridis, cividis, plasma, inferno. All perceptually uniform and colorblind-safe.
• Diverging (zero-centered): RdBu_r, coolwarm, PuOr. Colorblind-safe if tested.
• Never:
• Red AND green for categorical contrast (8% of men cannot distinguish)
• Rainbow / jet for sequential data (not perceptually uniform)
• More than 8 qualitative colors in one figure (saturates the reader's discrimination)
• Semantic consistency: if blue = model A in Figure 2, blue = model A in Figure 3. Pick a palette dictionary at the project level; reuse it everywhere. See docs/references/figure-guide.md for copy-paste hex codes.

4. No chart junk (Tufte)

• No 3D effects, drop shadows, gradient fills on bars, textures, or ornamental gridlines
• No frame around the plot area unless the journal explicitly requires it (most don't)
• Remove top and right spines (axes.spines.top: False, axes.spines.right: False) — they add ink without information
• Gridlines only when they aid reading specific values; if used, thin and light gray

5. Axes: label with units, human-readable ticks

• Every axis has a label. Every label includes units (except when units are counts or dimensionless ratios, in which case say so: "Accuracy" not "Accuracy (unitless)").
• Tick values are round numbers humans read quickly: 0, 0.25, 0.50, 0.75, 1.00 — not 0, 0.17, 0.33, 0.50, 0.67, 0.83.
• Avoid scientific notation unless the magnitude demands it; prefer log scale with integer decade ticks.

6. Legend: readable, non-overlapping

• Legend text at the same size as tick labels (or 1pt smaller, never smaller than 5pt)
• Position outside the data region when possible; if inside, never overlapping data points or error bars
• No legend frame unless the legend overlaps gridlines or other elements; prefer frameon=False
• If the categories are obvious (e.g., labeled directly on the lines), omit the legend entirely

7. Panel labels: lowercase, bold, top-left

• Multi-panel figures use (a), (b), (c), ... — lowercase, bold, sans-serif, in the top-left corner of each panel
• Consistent size across all panels (typically 8-10pt, larger than tick labels)
• Panel label does NOT overlap the plot content — place it in the figure margin, not on top of axes

8. Export format matches journal requirements

See the Journal Export Gate below for the table.

9. Legend self-containment (reviewer-grade)

Figure + legend alone must be interpretable without reading the main text. Reviewers often evaluate figures independently of the Methods section and the Results prose. If a reader can't understand the figure from the legend, the figure fails peer review regardless of how pretty it is.

10. Statistical reporting in legend (mandatory whenever statistical inference is shown)

Every figure with a statistical test, error bars, or group comparison must state in the legend:

• n = X per group/condition — exact number, not a range
• n definition — what n represents and sample independence where applicable. Examples by field: biology — "3 biological replicates (animals), 5 technical replicates each"; ML/physics — "10 independent random seeds"; psychology/HCI — "24 subjects, 40 trials each"; clinical — "50 patients, 1 scan each"
• Statistical test name — e.g., "one-way ANOVA with Tukey HSD post-hoc correction", "paired t-test", "Wilcoxon signed-rank"
• Error bar type — SEM, SD, or 95% CI. "Error bars" alone is not enough
• Center value — mean, median, or geometric mean
• p-value convention — prefer exact values (p = 0.003); if using asterisks, the legend must define them (`*p

Before calling savefig() (or equivalent), confirm the target journal's requirements from docs/references/figure-guide.md. If unknown, ask the user.

Inline summary (full table in docs/references/figure-guide.md):

| Journal family | 1-col width | 2-col width | Font | Font size | DPI (raster) | Preferred format | |---|---|---|---|---|---|---| | Nature family | 89mm | 183mm | Arial/Helvetica | 5-7pt | 300+ | PDF/AI/EPS for vector; TIFF/PNG for raster | | Science family | 55mm | 115/180mm | Helvetica | 6-12pt | 300+ | PDF/EPS preferred | | Cell family | 85mm | 174mm (full); 114mm (1.5-col) | Arial/Helvetica | 6-8pt | 300+ | PDF preferred; EPS/TIFF accepted | | JAMA / NEJM | 3.375" | 6.75" | Arial | 7-9pt | 300+ | EPS/PDF; TIFF for raster | | IEEE Transactions | 3.5" (88.9mm) | 7.16" (182mm) | Times/Helvetica | 8pt min | 300+ | PDF/EPS |

Per-Figure Workflow

For each figure, follow these steps in order:

Step 1: State the purpose

"This figure shows [what] for [what purpose], to support [what claim]."

If you can't finish that sentence, you're not ready to plot. Ask the user.

Step 2: Select the chart type

Use the Chart Type Selection Gate table. Write the choice in a comment at the top of the script: # Chart type: horizontal bar (compare 5 models on r²).

Step 3: Set the global style

At the top of the plotting script, call a style function that sets:

• Font family (sans-serif, Arial or Helvetica)
• TrueType embedding (pdf.fonttype = 42)
• Base font size (7pt for axis/ticks, 8pt for titles)
• Savefig DPI (600)
• Spine style (top and right off)
• Default palette (qualitative: Okabe-Ito; sequential: viridis)

See docs/references/figure-guide.md for a copy-paste-ready apply_paper_style() recipe.

Step 4: Render

Write the plotting code. Use named color variables, not hex strings inline. Keep one figure per script (or one composite function per script).

Step 5: Export

Call savefig('figures/fig_name.pdf', bbox_inches='tight', pad_inches=0.02). If a raster version is needed, also save .png at 600 DPI.

Step 6: Inline self-check

Before dispatching the reviewer, run through:

• [ ] Font is sans-serif (Arial/Helvetica) and embedded (TrueType)?
• [ ] All text ≥5pt?
• [ ] Palette is colorblind-safe (Okabe-Ito, viridis, or equivalent)?
• [ ] Every axis has a label with units?
• [ ] Every legend entry is readable without zooming?
• [ ] No 3D effects, gradients, or rainbow cmap?
• [ ] Top and right spines removed?
• [ ] Panel labels (if multi-panel) are lowercase bold top-left?
• [ ] Output is PDF or SVG (not JPEG)?
• [ ] Figure legend names n, statistical test, error bar type, and center value?
• [ ] Legend is interpretable without reading the main text?
• [ ] Sample independence clarified where applicable (biological vs technical replicates; independent vs repeated measures; subjects vs trials)?
• [ ] No dynamite plots when sample size permits raw overlay (N ≤ 50 per group)?
• [ ] Representative images labeled as such; quantified images state N?

Step 7: Dispatch figure-reviewer subagent

Locate the reviewer prompt at skills/figure-design/figure-reviewer-prompt.md. Fill the placeholders:

• {FIGURE_PATH} — path to the output file (e.g., figures/fig3.pdf)
• {SCRIPT_PATH} — path to the generating script
• {FIGURE_PURPOSE} — one-sentence purpose from Step 1
• {TARGET_JOURNAL} — e.g., "Nature Communications"
• {CAPTION_TEXT} — the draft caption (if written), else "N/A"

Dispatch via Task tool (general-purpose subagent). Wait for Status: Approved or Status: Issues Found.

Step 8: Act on feedback

• Status: Approved → move to the next figure or back to manuscript-writing
• Status: Issues Found → fix each issue in the script, re-render, re-dispatch the reviewer. Repeat until approved.

If the reviewer flags the same issue twice, escalate to the user.

Step 9: Commit

Both the script (.py/.R/.jl) AND the output file (.pdf/.svg) go to git. The output file is a build artifact, but committing it protects against environment drift — the paper reader can see what the authors saw even if their TeX/matplotlib environment differs.

Common Rationalizations

| Excuse | Reality | |---|---| | "Default matplotlib style is fine for now" | Default is 100 DPI, bitmap fonts, blue axis labels. Journals silently reject; reviewers assume carelessness. Set the style upfront, not later. | | "Viridis is overused, let me pick a prettier palette" | Viridis is perceptually uniform AND colorblind-safe. Pretty is irrelevant; the reader's job is to decode, not admire. | | "I'll fix the typography later in Illustrator" | Manual edits break reproducibility (claims-audit fails). Anyone running the script should get the submitted figure byte-for-byte. Fix in the script. | | "Pie chart is fine, it's only 3 categories" | Horizontal bar beats pie at any N. Humans compare lengths faster and more accurately than angles. | | "The legend fits if I shrink it" | Sub-5pt text is unreadable in print. Move the legend outside the axes, split panels, or drop it entirely — never shrink below 5pt. | | "Red vs green is intuitive for error/success" | 8% of men see them as the same color. Use blue/orange, add shape coding, or annotate directly. | | "The figure looks fine on my screen" | Screens are 100-200 DPI RGB. Print is 300+ DPI CMYK. Always export to PDF and inspect at 100% zoom before declaring done. | | "Journal guidelines are for final submission — draft can be loose" | Drafts become submissions through editorial inertia. Fixing typography at submission time is 10x the cost of setting a global style once. | | "I'll just screenshot the Jupyter notebook output" | Screenshots are raster at screen DPI, no vector, no TrueType. Always save via savefig('.pdf')

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jeonnoin-alt
• Source: jeonnoin-alt/Eureka
• License: MIT
• Homepage: https://github.com/jeonnoin-alt/Eureka

Install and usage instructions live in the source repository linked above.