Figure prep

Figures carry the result. Get the encoding honest first, the layout second, and the caption last.

1. Decide what kind of figure this is

Before drawing anything, load_skill with id scientific-visualization and read references/publication_guidelines.md. Its non-negotiables apply here in full: never alter or hide data to improve a figure, keep bar baselines at zero, name what an error bar actually is, distinguish missing from zero, and never claim a palette or a DPI number makes a figure accessible.

2. Check which figure tools the run has

The figure tools come with the ordinary chat run, next to the file and compile tools. Which ones are there depends on the engine.

When preview_figure is missing, say why in one line (a Markdown project, or an engine that has not loaded yet) and build the figure as a file instead.

3. TikZ

references/tikz-recipes.md in this skill has Tectonic-safe starting points for boxes and arrows, grouping, pgfplots, colors, and sizing, plus what the isolated preview does and does not share with the manuscript.

With preview_figure

1. preview_figure with code (the \begin{tikzpicture}...\end{tikzpicture} body), plus packages and libraries it needs. tikz is always included; name libraries explicitly, for example arrows.meta, positioning, fit, calc, backgrounds, patterns.
2. Read success, errors and log_tail. On failure, fix and call again.
3. The rendered page is handed to the model when the model can see images, so iterate on what it actually looks like: overlapping labels, arrows landing on the wrong anchor, a node wider than its box.
4. insert_figure with the final code, a caption and a label. It wraps the code in \begin{figure}[htbp]\centering ... \end{figure} at the user's cursor and saves a PNG copy under figures/<slug>.png.

Two things to know about insert_figure:

• The document ends up holding the TikZ source inline, not an \includegraphics. The PNG under figures/ is a reference copy, not what the PDF uses.
• It inserts [htbp]. Papers usually want [t]. Fix that afterwards with replace_in_file.

As a file

1. write_file the figure to figures/<name>.tex containing just the tikzpicture.
2. \input{figures/<name>} inside a figure environment in the section that discusses it.
3. compile, then verify_pdf_pages on the page that holds it to see the result.

This is the only drawing route on Markdown projects.

In a Typst project

Draw with CeTZ for diagrams and plots (cetz-plot for data plots), fletcher for node and arrow diagrams, or plain Typst (rect, grid, stack) for simple layouts.

1. preview_figure with code as Typst markup. Put the imports it needs at the top, each with an exact version:

   #import "@preview/cetz:0.4.2"
   #cetz.canvas({
     import cetz.draw: *
     rect((0, 0), (2, 1), name: "enc")
     content("enc", [Encoder])
     rect((3, 0), (5, 1), name: "dec")
     content("dec", [Decoder])
     line("enc.east", "dec.west", mark: (end: ">"))
   })
   

   packages and libraries are for LaTeX and are ignored here. The figure renders alone on a white page, so it cannot read project files such as images or data. Put small data inline, or place a finished image with image(...) in the manuscript instead.

2. Read success, errors and warnings. Line numbers count from the first line of your code. The first use of a package version downloads it, so that preview needs network.

3. Iterate on the rendered image the same way as for TikZ.

4. insert_figure with the final code, a caption and a label such as fig:pipeline. It moves the leading #import lines above the figure and skips any the document already has, wraps the rest in #figure(caption: [...])[ ... ], puts <fig:pipeline> after it, and saves a PNG copy under figures/. Refer to it with @fig:pipeline.

4. Matplotlib

Scripts live in the project so the figure is reproducible.

1. create_file a scripts/ folder and figures/ if they do not exist.
2. write_file scripts/figure_<name>.py. Keep the data path, the transformations and the seed inside the script.
3. run_command with python3 scripts/figure_<name>.py. This asks the user for approval, runs in the project directory, has a 120 second budget, and inherits the login shell environment. There is no sandbox, so keep the script to reading its input and writing its output.
4. Export PDF into figures/. Vector text stays sharp and searchable at any size. In a Typst project, SVG works on every version and PDF works from Typst 0.14 on, so check typst.version in project.json before you pick PDF.
5. read_skill_file scientific-visualization for depth: references/journal_requirements.md for sizes and formats, references/color_palettes.md for palettes, assets/publication.mplstyle and assets/presentation.mplstyle for style sheets, assets/color_palettes.py and scripts/style_presets.py for the presets, scripts/figure_export.py for an exporter that refuses silent overwrites and records provenance.

Those scripts sit in the skill directory, not the project. load_skill returns the absolute directory, so run one as python3 "<skill dir>/scripts/style_presets.py", or copy the parts you need into the project script. They need Python 3.11 or newer.

references/matplotlib-route.md in this skill has the concrete shape of a figure script, the sizing table, and what to do when Python is missing.

5. Wire it into the manuscript

\begin{figure}[t]
  \centering
  \includegraphics[width=\linewidth]{figures/architecture.pdf}
  \caption{System architecture. The encoder on the left feeds the fusion module.}
  \label{fig:architecture}
\end{figure}

Rules that are not negotiable:

• width=\linewidth, or a fraction of it. Not \textwidth inside a two-column layout.
• Caption below a figure, above a table. \label after \caption, never before, or every reference points at the enclosing section.
• Refer with \cref{fig:architecture} from cleveref, which writes the word for you. With plain \ref, put a ~ in front: Figure~\ref{fig:architecture}.
• [t] is the right default for papers. [h] alone is ignored by LaTeX. [H] from the float package forces placement and breaks page flow, so keep it for reports.
• Every figure is referenced from the text at least once. project_map reports labels; check nothing is orphaned.
• Full-width figure in a two-column layout: figure*.
• Subfigures come from subcaption. Never load subfigure or subfig.

In a Typst project the same figure looks like this:

#figure(
  image("figures/architecture.svg", width: 100%),
  caption: [System architecture. The encoder on the left feeds the fusion module.],
  placement: top,
) <fig:architecture>

• Refer with @fig:architecture, which prints the supplement and number for you.
• The label goes after the closing parenthesis, outside the call.
• placement: top floats the figure like [t] does. Leave it out to keep the figure where it is in the text.
• Typst puts every caption below by default. For tables above, add #show figure.where(kind: table): set figure.caption(position: top) once near the top of the document.
• Full width in a two-column layout: placement: top with scope: "parent".

Captions carry the claim. First sentence says what the figure shows, the rest says what to notice. A caption that only names the axes is wasted.

6. Hand off

• Conceptual diagrams that resist precise drawing: scientific-schematics. Read its references/best_practices.md and references/iterative_refinement.md. Its image-generation scripts are deliberately not bundled with Oleafly, because they call an external image service and read .env files from parent directories, so treat that skill as guidance and draw the figure here.
• Figure design theory, palettes, journal export rules: scientific-visualization.
• Compile failures anywhere in this loop: oleafly-latex-build.
• Figures for a deck or a poster: oleafly-slides-and-posters.

Publication quality checklist

• The encoding is honest: zero baselines for bars, no truncated axis that manufactures an effect, missing data shown as missing
• Uncertainty is named in the caption, with n and the unit of replication
• Color is never the only cue. Every series also differs by marker, line style, hatch, or a direct label
• The palette survives grayscale and common color-vision deficiencies. Okabe-Ito is a safe default
• Font size at final printed size is close to the body text, roughly 7 to 9 pt for most journals. Set the figure's physical width, do not scale it in \includegraphics
• Vector (PDF) for plots and diagrams. Raster only for photographs and screenshots, at 300 dpi or better. Never JPEG for a plot
• Axis labels carry units. Tick labels are not scientific notation soup
• The figure is referenced from the text and the reference reads correctly in the PDF
• The caption states the claim, not just the contents
• It was looked at in the compiled PDF at final size, with verify_pdf_pages where available

Failure handling

Artifacts

figures/*.pdf or figures/*.png, scripts/figure_*.py where Python was used, the figure environment in the manuscript, and a compiled PDF that shows the figure in place.

Done when

• The figure compiles as part of the whole document, not only in isolation
• It is referenced from the text and the cross-reference resolves
• The caption and label are present, in the right order
• The checklist above was worked through, and anything skipped was named
• The source that produces it (TikZ or Typst code, or a Python script) is in the project

From a terminal

Outside the app (a terminal, or a coding agent with a shell), the oleafly command does the same work. Always pass --json and check ok.