paper-visual-craft git:20260715.9c5b5aaA

Immutable. This exact content is served forever at /api/v1/blob/6b10c4dc186b3177.

---
name: paper-visual-craft
description: Use when designing, redrawing, or validating research-paper figures and tables, including Matplotlib plots, LaTeX tables, benchmarks, captions, legends, annotations, color, and typography. Preserves exact evidence and checks rendered PDFs for clipping, overlap, and readability.
license: MIT
---

# Paper Visual Craft

## Routing Boundary

- Use `$paper-framework-figure-studio-pro` first for source-grounded framework
  figure, method overview, architecture diagram, pipeline/process figure,
  system/data-flow figure, mechanism schematic, or agent workflow planning.
- Return to `$paper-visual-craft` for final figure/table polish, Matplotlib or
  LaTeX edits, captions, color/typography cleanup, and rendered PDF/PNG
  validation.

## Core Workflow

1. Inspect before editing.
   - Read the paper context around the target figure or table.
   - Locate the source data, generation script, LaTeX include block, captions, and any reference visual the user named.
   - If data provenance is unclear, stop and identify the exact missing source instead of redrawing from copied numbers.

2. Classify the visual.
   - Decide whether it is a main-result figure, appendix diagnostic, dataset/statistics figure, ablation table, reliability/control table, or qualitative panel.
   - Keep main-paper visuals compact and claim-focused. Use appendix visuals for diagnostics, extended controls, and richer tables.
   - For dataset or benchmark papers, ask what story the visual supports: benchmark positioning, annotation effort, evidence source, main control, or diagnostic richness.
   - Put the comparison axis first. The reader should immediately know what is
     being compared and what conclusion to read; the visual should not preserve
     implementation history, generated-condition inventories, or debug process
     unless those are the claim.
   - Prefer a simple table for categorical comparisons and component ablations.
     Do not turn a row-and-column question into a complex diagram merely to make
     the presentation look more elaborate.

3. Freeze the table contract before experiments.
   - When planning results, define the final rows, columns, comparison axis,
     claim owner, and reference row before runs start.
   - For each metric, record its plain definition, unit, direction, aggregation
     population, precision, and any delta reference or sign convention.
   - If a LaTeX manuscript is in scope, add the final table scaffold there. Use
     `--` for unavailable values and keep internal completion status out of the
     caption and paper prose.

4. Preserve measurement integrity.
   - Preserve exact values, units, sample counts, conditions, and axis semantics.
   - Do not mix raw values, percentages, percentage-point deltas, and relative deltas inside one visual unless the caption makes the units explicit.
   - When adding a numeric result row, fit the row to the table's existing
     measurement schema before inserting it. If the table uses reference cells,
     deltas, arrows, or semantic colors, compute the appropriate comparison
     against the named reference with the same precision and directionality.
     Do not paste raw values into a delta-coded table.
   - Put interpretation in captions or prose, not inside plot areas, unless a small label clarifies a data point without occluding information.
   - For diagnostic figures, show metric behavior without implying a causal
     mechanism unless the experimental design directly tests causality. The
     caption should say what the diagnostic supports and what it does not prove.
   - When table rows, columns, panels, or layout change, update the caption,
     nearby prose, cross-references, and later interpretive paragraphs in the
     same pass. A table edit is incomplete if the surrounding text still
     describes the old rows or comparison target, or if a new row omits the
     table's required reference/delta semantics.

5. Design with restrained hierarchy.
   - Prefer vector outputs for papers and PNG previews for inspection.
   - Use consistent legends, typography, line weights, tick formatting, row highlights, and caption structure.
   - Reserve whitespace for endpoint labels and callouts; avoid labels floating over trends, bars, or dense table cells.
   - For table heatmaps, use semantic color rather than raw sign, fixed-width colored cells, and delta text that is visually smaller than the main value.
   - When a caption defines color semantics, color the color words themselves, such as green, red, amber, or blue.
   - Do not use unconditional table resizing to make a table fill the page width. Resize only to shrink a naturally overwide table; never enlarge a table that already fits.
   - Preserve the reader's intended comparison axis. For appendix diagnostics,
     do not split one wide table into panels merely because it is wide; if the
     user permits `resizebox` and horizontal scanning is the point, keep one
     coherent table and shrink it only as needed.
   - For planned experiments, create a clean paper-style table scaffold with
     `--` for missing metrics instead of leaving prose TODOs; keep the caption
     focused on the comparison contract and do not interpret placeholder values.
   - Prune redundancy. Delete or merge duplicate controls, equivalent inputs,
     uninformative panels, and plain scatter plots with no clear message. Fewer
     clear visuals are better than a "fancy" but unfocused figure set.
   - Use icons only when they reduce text and are reproducible from LaTeX or an existing project icon system. Do not copy external paper image assets.

6. Validate rendered output.
   - Compile the paper or render the affected standalone output.
   - Inspect the rendered PDF/PNG visually for clipping, overlap, crowded ticks, unreadable labels, broken references, excessive table scaling, and color imbalance.
   - For dense colored tables, render-check the affected pages at least twice after the final edit.
   - Report exact files changed, commands run, and any remaining visual risk.

## Table Polish Reminders

- Use semantic color, not raw sign: color should answer whether the value is better, worse, a reference, or a diagnostic warning.
- Make tables serve the paper story. A table should let the reader scan the experimental question and evidence, not reconstruct the implementation chronology.
- Make each main table answer one reviewer question. Put the primary comparison
  before ablations and diagnostics, and remove metrics that do not change how
  the claim is interpreted.
- Make the comparison axis explicit before optimizing style. If the reader
  cannot tell whether rows compare models, controls, tasks, or implementation
  variants, redesign the table before polishing colors.
- Keep colored metric cells visually uniform with fixed-width columns; avoid short values producing tiny color patches.
- Make delta text secondary to the main value through smaller type and compact arrows.
- Before finalizing a new numeric row, audit every metric cell against the
  table contract: reference row, delta sign, lower-is-better or higher-is-better
  direction, color meaning, precision, and surrounding prose. A correct number
  in the wrong cell format is still a table error.
- When captions define color semantics, color the color words themselves, such as green, red, amber, and blue.
- Do not wrap fitting tables in `\resizebox{\linewidth}{!}` or `\resizebox{\textwidth}{!}` just to fill space. Prefer native size; if width protection is needed, use a max-width wrapper that can shrink but cannot enlarge.
- Treat splitting a table into panels as a design decision, not an automatic
  fallback. Split only when separate panels improve the reader's comparison;
  otherwise keep a unified wide table when it preserves scanability. If the
  user explicitly allows `resizebox` and horizontal scanning is the core value,
  prefer one coherent shrunken table over two panels.
- Always compile and render-check dense table pages after LaTeX edits, especially when adding cell-level color or rank cues.
- When a result is not ready, reserve the accepted row/column structure with
  `--` only if the experiment is part of the paper story. Do not expose internal
  completion status in the caption or infer claims from blank cells.

## Reference Routing

- Read `references/plot-design.md` for Matplotlib figures, line plots, bars, subfigure panels, palettes, legends, annotations, and vector export.
- Read `references/table-design.md` for LaTeX tables, benchmark comparisons, grouped headers, row coloring, icons, compact captions, and table density.
- Read `references/drivebench-patterns.md` when the user asks to borrow DriveBench-style design or when a benchmark table/control diagnostic needs that visual language.
- Read `references/validation-checklist.md` before finalizing any figure or table that will appear in a compiled paper PDF.

## Default Decisions

- Use a portable style; do not hardcode repository paths, dataset names, or paper-specific macros unless the current project already defines them.
- Prefer editing the existing figure/table generator over hand-editing generated outputs.
- Prefer true LaTeX subfigures or minipages with visible panel captions over a single combined image when panels need independent captions.
- Prefer compact table rows with short cells over long explanatory text in the table body.
- Treat judge scores, robustness diagnostics, and qualitative audits as secondary unless the paper explicitly makes them primary evidence.