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

<HARD-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. </HARD-GATE>

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 < 0.05, **p < 0.01, ***p < 0.001)

Missing any one of these is the single most common figure-related reviewer flag at top-tier journals.

11. Raw data visibility — no dynamite plots

For distributions or group comparisons, show individual data points overlaid on summary statistics whenever sample size permits (violin + strip, box + jitter, raincloud, strip plot with mean line). Bar chart of mean + error whisker alone ("dynamite plot") is the #1 flagged visualization anti-pattern in top-journal review (eLife: Ten common statistical mistakes). The rule of thumb: overlay raw points when N per group ≤ 50; above that overlay becomes illegible and summary statistics are acceptable.

Journal Export Gate

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

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

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

Red Flags — STOP

• Generating a figure inside a notebook cell with no saved script file
• Editing the output PDF manually in Illustrator or Inkscape
• Using jet / rainbow cmap for a sequential quantity
• Any text below 5pt in the figure
• 3D bar chart, 3D pie, gradient-filled categorical bars
• Red + green as the only two colors distinguishing categories
• Axis without a label
• Legend overlapping data points or error bars
• Panel labels in a different font from the tick labels
• Saving as .jpg or a screenshot-based format
• "I'll clean it up before submission" (no — clean it up now)
• Legend missing n, statistical test, or error bar definition
• Bar chart of mean values with no raw data overlay (dynamite plot) when N per group ≤ 50
• Image panel without "representative of N" label or quantification N stated

Orthogonality with claims-audit

figure-design and claims-audit Part B (Figure Integrity) are orthogonal and both run:

A figure can pass one and fail the other. Both must pass for submission-readiness.

Integration

• Called by: eureka:using-eureka when figure creation intent is detected; eureka:manuscript-writing when Results section cites a figure
• Prerequisite: data exists + analysis complete (a figure has nothing to show otherwise)
• Invokes: figure-reviewer subagent (per figure, after rendering)
• Pairs with: eureka:claims-audit (integrity) — orthogonal, both run before submission
• Reference: docs/references/figure-guide.md (for journal-specific specs, palette hex codes, matplotlib style recipe, accessibility tools, chart-type flowchart)

Skill Type

FLEXIBLE — Chart type, palette choice, and journal target adapt to the user's field, data, and venue. The iron laws (colorblind-safe palette, 5pt font floor, TrueType embedding, no chart junk, vector export, script-generated only) are fixed.